@rebyteai/agent-react 0.3.0 → 0.6.0

package/README.md

@@ -1,5 +1,7 @@
 # @rebyteai/agent-react
 
+The function-wait state and `submitToolResult` below require version 0.4.0 or later.
+
 Install the versioned package (no repository clone required):
 
 ```sh
@@ -29,11 +31,36 @@ Each assistant message has a `turnId` and a presentation-only `projection`:
 Built-in server functions are distinct from client functions. A completed client
 result updates its matching call; the actual handoff is Session `requires_action`.
 
-History is restored from persisted Items and Turns. A recovered active Session is
-polled until settled. Live disconnects report an error; reload recovers output
-without resending input. The hook reports client-tool waiting as an error and does
-not run application handlers or submit their outputs. For those workflows, use
-the [Agents API recipe](../../examples/agents-api/README.md) or Commerce adapter.
+History is restored from persisted Items and Turns. A recovered active or waiting
+Session is polled until settled. Live disconnects report an error; reload recovers
+output without resending input.
+
+## Application functions
+
+`chat.status === 'requires_action'` is a normal waiting state. Read
+`chat.requiredActions`; execute only these authoritative calls, never every
+`function_call` Item. The hook leaves execution to your application and continues
+observing while an external backend worker supplies results.
+
+An application handler can explicitly return a saved result through the hook:
+
+```tsx
+// Called by your application's function handler, not on every React render.
+await chat.submitToolResult({
+  turn_id: action.turn_id, call_id: action.call_id,
+  success: true, output: JSON.stringify(result),
+})
+// Failure: { turn_id, call_id, success: false, error: 'Lookup failed' }
+```
+
+The method submits one result per request and reuses a stable per-call idempotency
+key. Persist side effects and results by `call_id` in your application; a reload
+or repeated notification is not authorization to execute a side effect twice.
+Both ordinary functions and functions inside Dynamic Workflow use this path.
+`send()` remains pending through handoffs until the Turn settles. `stop()` cancels
+waiting work too. Reload restores the pending actions and observes subsequent
+results; it never automatically executes your handler. See the
+[Agents API recipes](../../examples/agents-api/README.md) for backend consumers.
 
 Images are uploaded as Session files. The model can use hosted `view_image` to
 inspect them; the upload itself is not an inline model image message. No browser

package/dist/index.cjs

@@ -154,7 +154,7 @@ function projectSessionItem(state, item, index) {
   }
   if (item.type === "function_call_output") return { ...state, toolCalls: state.toolCalls.map((tool) => tool.callId === item.call_id ? { ...tool, status: item.status, output: typeof item.output === "string" ? item.output : JSON.stringify(item.output), error: item.error } : tool) };
   if (item.type !== "command_execution" && item.type !== "mcp_call" && item.type !== "function_call") return state;
-  const serverFunction = item.type === "function_call" && ["write_stdin", "apply_patch", "view_image", "list_mcp_resources", "list_mcp_resource_templates", "read_mcp_resource", "rebyte_web_search"].includes(item.name);
+  const serverFunction = item.type === "function_call" && ["write_stdin", "apply_patch", "view_image", "list_mcp_resources", "list_mcp_resource_templates", "read_mcp_resource", "rebyte_web_search", "tool_search", "run_code"].includes(item.name);
   const value = {
     id: item.id,
     outputIndex: index,
@@ -172,7 +172,8 @@ function projectSessionItem(state, item, index) {
 function reduceSessionEvent(state, event) {
   let next = { ...state, events: [...state.events, event] };
   if (event.type === "agent.session.turn.item.added" || event.type === "agent.session.turn.item.done") {
-    if (event.output_index !== null) next = projectSessionItem(next, event.item, event.output_index);
+    if (event.item.type === "function_call_output") next = projectSessionItem(next, event.item, 0);
+    else if (event.output_index !== null) next = projectSessionItem(next, event.item, event.output_index);
   } else if (event.type === "agent.session.turn.output_text.delta") {
     if (!next.textMessages.some((message) => message.id === event.item_id)) throw new Error("Text delta has no message");
     const messages = next.textMessages.map((message) => message.id === event.item_id ? { ...message, text: message.text + event.delta } : message);
@@ -195,6 +196,7 @@ function useAgentSession(options) {
   const [error, setError] = (0, import_react.useState)(null);
   const [sessionId, setSessionId] = (0, import_react.useState)(options.initialSessionId ?? null);
   const [artifacts, setArtifacts] = (0, import_react.useState)([]);
+  const [requiredActions, setRequiredActions] = (0, import_react.useState)([]);
   const idRef = (0, import_react.useRef)(sessionId);
   const creating = (0, import_react.useRef)(null);
   const active = (0, import_react.useRef)(null);
@@ -235,7 +237,7 @@ function useAgentSession(options) {
         if (item.type === "message" && item.role === "user" && item.id !== null) restored.push({ id: item.id, role: "user", content: item.content.filter((part) => part.type === "input_text").map((part) => part.text).join("\n"), status: "completed", turnId: null, projection: null });
       }
       const projection = sessionItemState(turnItems);
-      restored.push({ id: turn.id, role: "assistant", content: projection.textMessages.map((item) => item.text).join("\n\n"), status: turn.status === "failed" ? "failed" : turn.status === "cancelled" ? "cancelled" : turn.status === "completed" ? "completed" : "streaming", turnId: turn.id, projection: { ...projection, turnId: turn.id } });
+      restored.push({ id: turn.id, role: "assistant", content: projection.textMessages.map((item) => item.text).join("\n\n"), status: turn.status === "failed" ? "failed" : turn.status === "cancelled" ? "cancelled" : turn.status === "completed" ? "completed" : turn.status === "waiting" ? "waiting" : "streaming", turnId: turn.id, projection: { ...projection, turnId: turn.id } });
     }
     setMessages((previous) => restored.map((message) => {
       const existing = previous.find((value) => value.turnId !== null && value.turnId === message.turnId);
@@ -245,7 +247,9 @@ function useAgentSession(options) {
   }, [transport]);
   (0, import_react.useEffect)(() => {
     const id = initial.current;
-    if (!id) return;
+    if (!id) return () => {
+      active.current?.abort();
+    };
     let cancelled = false;
     busy.current = true;
     setStatus("streaming");
@@ -253,11 +257,13 @@ function useAgentSession(options) {
       await refresh(id);
       while (!cancelled) {
         const session = await transport.retrieve(id);
-        if (session.status !== "in_progress") {
+        if (cancelled) return;
+        setRequiredActions(session.required_actions);
+        if (session.status !== "in_progress" && session.status !== "requires_action") {
           if (session.status === "failed") throw new Error(session.error ?? "Session failed");
-          if (session.status === "requires_action") throw new Error("Session is waiting for a client tool result");
           break;
         }
+        setStatus(session.status === "requires_action" ? "requires_action" : "streaming");
         await new Promise((resolve) => setTimeout(resolve, 1e3));
         if (!cancelled) await refresh(id);
       }
@@ -284,6 +290,7 @@ function useAgentSession(options) {
     submitted.current = false;
     setStatus("streaming");
     setError(null);
+    setRequiredActions([]);
     const abort = new AbortController();
     active.current = abort;
     const assistantId = crypto.randomUUID();
@@ -317,12 +324,18 @@ function useAgentSession(options) {
         setMessages((previous) => previous.map((message) => message.id === assistantId ? { ...message, content: projection.textMessages.map((item) => item.text).join("\n\n"), turnId: projection.turnId, projection } : message));
         if (event.type === "agent.session.turn.completed" || event.type === "agent.session.turn.cancelled" || event.type === "agent.session.turn.failed") {
           await refresh(id);
+          setRequiredActions([]);
           if (event.type === "agent.session.turn.failed") throw new Error(event.turn.error?.message ?? "Turn failed");
           setStatus("idle");
           return event.turn;
         }
         if (event.type === "agent.session.failed") throw new Error(event.session.error ?? "Session failed");
-        if (event.type === "agent.session.requires_action") throw new Error("Session is waiting for a client tool result");
+        if (event.type === "agent.session.requires_action" || event.type === "agent.session.in_progress") {
+          const waiting = event.type === "agent.session.requires_action";
+          setRequiredActions(event.session.required_actions);
+          setStatus(waiting ? "requires_action" : "streaming");
+          setMessages((previous) => previous.map((message) => message.id === assistantId ? { ...message, status: waiting ? "waiting" : "streaming" } : message));
+        }
         if (event.type === "error") throw new Error(event.error.message);
       }
       throw new Error("Session event stream disconnected. Reload to recover persisted output.");
@@ -348,12 +361,26 @@ function useAgentSession(options) {
       throw fail(cause);
     }
   }, [transport, fail]);
+  const submitToolResult = (0, import_react.useCallback)(async (result) => {
+    const id = idRef.current;
+    if (!id) throw new Error("No Session is waiting for a function result");
+    setError(null);
+    try {
+      await transport.submit(id, [{ type: "agent.session.input.tool_result", ...result }], `agent-result:${result.turn_id}:${result.call_id}`);
+    } catch (cause) {
+      const failure = cause instanceof Error ? cause : new Error(String(cause));
+      setError(failure);
+      throw failure;
+    }
+  }, [transport]);
   return {
     messages,
     status,
     error,
     sessionId,
     artifacts,
+    requiredActions,
+    submitToolResult,
     send,
     stop,
     async upload(file, progress) {
@@ -368,6 +395,7 @@ function useAgentSession(options) {
       setSessionId(null);
       setMessages([]);
       setArtifacts([]);
+      setRequiredActions([]);
       setError(null);
       setStatus("idle");
       onSession?.(null);

package/dist/index.d.cts

@@ -1,4 +1,4 @@
-import { AgentSessionEvent, AgentSession, AgentSessionInputParam, AgentSessionItem } from 'openai/resources/beta/agents/agents';
+import { AgentSessionEvent, AgentSession, AgentSessionInputParam, AgentSessionItem, AgentFunctionCallOutputParam } from 'openai/resources/beta/agents/agents';
 export { AgentSession, AgentSessionEvent } from 'openai/resources/beta/agents/agents';
 import { Turn } from 'openai/resources/beta/agents/sessions/turns';
 export { Turn } from 'openai/resources/beta/agents/sessions/turns';
@@ -60,7 +60,7 @@ interface AgentChatMessage {
     role: 'user' | 'assistant';
     content: string;
     attachments?: AgentAttachment[];
-    status: 'completed' | 'streaming' | 'failed' | 'cancelled';
+    status: 'completed' | 'streaming' | 'waiting' | 'failed' | 'cancelled';
     turnId: string | null;
     projection: TurnState | null;
 }
@@ -85,14 +85,29 @@ declare function createAgentSessionTransport(options: {
     fetch?: typeof fetch;
 }): AgentSessionTransport;
 
+type AgentRequiredAction = AgentSession['required_actions'][number];
+/** One result per request also supports functions called inside Dynamic Workflow. */
+type AgentToolResult = {
+    turn_id: string;
+    call_id: string;
+} & ({
+    success: true;
+    output: AgentFunctionCallOutputParam;
+} | {
+    success: false;
+    error: string;
+});
 interface AgentSessionChat {
     messages: AgentChatMessage[];
-    status: 'idle' | 'streaming' | 'error';
+    status: 'idle' | 'streaming' | 'requires_action' | 'error';
     error: Error | null;
     sessionId: string | null;
     artifacts: Array<SessionArtifact & {
         url: string;
     }>;
+    requiredActions: AgentRequiredAction[];
+    /** Submit an already executed function's result; the application owns execution and deduplication. */
+    submitToolResult(result: AgentToolResult): Promise<void>;
     send(input: string | AgentChatInput): Promise<Turn | null>;
     upload(file: File, progress?: (value: AgentUploadProgress) => void): Promise<SessionAttachment>;
     stop(): Promise<void>;
@@ -104,4 +119,4 @@ declare function useAgentSession(options: {
     onSession?: (id: string | null) => void;
 }): AgentSessionChat;
 
-export { type AgentAttachment, type AgentChatInput, type AgentChatMessage, type AgentSessionChat, type AgentSessionTransport, AgentTransportError, type AgentUploadProgress, type SessionAttachment, type TextMessageState, type ToolCallState, type TurnState, createAgentSessionTransport, useAgentSession };
+export { type AgentAttachment, type AgentChatInput, type AgentChatMessage, type AgentRequiredAction, type AgentSessionChat, type AgentSessionTransport, type AgentToolResult, AgentTransportError, type AgentUploadProgress, type SessionAttachment, type TextMessageState, type ToolCallState, type TurnState, createAgentSessionTransport, useAgentSession };

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { AgentSessionEvent, AgentSession, AgentSessionInputParam, AgentSessionItem } from 'openai/resources/beta/agents/agents';
+import { AgentSessionEvent, AgentSession, AgentSessionInputParam, AgentSessionItem, AgentFunctionCallOutputParam } from 'openai/resources/beta/agents/agents';
 export { AgentSession, AgentSessionEvent } from 'openai/resources/beta/agents/agents';
 import { Turn } from 'openai/resources/beta/agents/sessions/turns';
 export { Turn } from 'openai/resources/beta/agents/sessions/turns';
@@ -60,7 +60,7 @@ interface AgentChatMessage {
     role: 'user' | 'assistant';
     content: string;
     attachments?: AgentAttachment[];
-    status: 'completed' | 'streaming' | 'failed' | 'cancelled';
+    status: 'completed' | 'streaming' | 'waiting' | 'failed' | 'cancelled';
     turnId: string | null;
     projection: TurnState | null;
 }
@@ -85,14 +85,29 @@ declare function createAgentSessionTransport(options: {
     fetch?: typeof fetch;
 }): AgentSessionTransport;
 
+type AgentRequiredAction = AgentSession['required_actions'][number];
+/** One result per request also supports functions called inside Dynamic Workflow. */
+type AgentToolResult = {
+    turn_id: string;
+    call_id: string;
+} & ({
+    success: true;
+    output: AgentFunctionCallOutputParam;
+} | {
+    success: false;
+    error: string;
+});
 interface AgentSessionChat {
     messages: AgentChatMessage[];
-    status: 'idle' | 'streaming' | 'error';
+    status: 'idle' | 'streaming' | 'requires_action' | 'error';
     error: Error | null;
     sessionId: string | null;
     artifacts: Array<SessionArtifact & {
         url: string;
     }>;
+    requiredActions: AgentRequiredAction[];
+    /** Submit an already executed function's result; the application owns execution and deduplication. */
+    submitToolResult(result: AgentToolResult): Promise<void>;
     send(input: string | AgentChatInput): Promise<Turn | null>;
     upload(file: File, progress?: (value: AgentUploadProgress) => void): Promise<SessionAttachment>;
     stop(): Promise<void>;
@@ -104,4 +119,4 @@ declare function useAgentSession(options: {
     onSession?: (id: string | null) => void;
 }): AgentSessionChat;
 
-export { type AgentAttachment, type AgentChatInput, type AgentChatMessage, type AgentSessionChat, type AgentSessionTransport, AgentTransportError, type AgentUploadProgress, type SessionAttachment, type TextMessageState, type ToolCallState, type TurnState, createAgentSessionTransport, useAgentSession };
+export { type AgentAttachment, type AgentChatInput, type AgentChatMessage, type AgentRequiredAction, type AgentSessionChat, type AgentSessionTransport, type AgentToolResult, AgentTransportError, type AgentUploadProgress, type SessionAttachment, type TextMessageState, type ToolCallState, type TurnState, createAgentSessionTransport, useAgentSession };

package/dist/index.js

@@ -126,7 +126,7 @@ function projectSessionItem(state, item, index) {
   }
   if (item.type === "function_call_output") return { ...state, toolCalls: state.toolCalls.map((tool) => tool.callId === item.call_id ? { ...tool, status: item.status, output: typeof item.output === "string" ? item.output : JSON.stringify(item.output), error: item.error } : tool) };
   if (item.type !== "command_execution" && item.type !== "mcp_call" && item.type !== "function_call") return state;
-  const serverFunction = item.type === "function_call" && ["write_stdin", "apply_patch", "view_image", "list_mcp_resources", "list_mcp_resource_templates", "read_mcp_resource", "rebyte_web_search"].includes(item.name);
+  const serverFunction = item.type === "function_call" && ["write_stdin", "apply_patch", "view_image", "list_mcp_resources", "list_mcp_resource_templates", "read_mcp_resource", "rebyte_web_search", "tool_search", "run_code"].includes(item.name);
   const value = {
     id: item.id,
     outputIndex: index,
@@ -144,7 +144,8 @@ function projectSessionItem(state, item, index) {
 function reduceSessionEvent(state, event) {
   let next = { ...state, events: [...state.events, event] };
   if (event.type === "agent.session.turn.item.added" || event.type === "agent.session.turn.item.done") {
-    if (event.output_index !== null) next = projectSessionItem(next, event.item, event.output_index);
+    if (event.item.type === "function_call_output") next = projectSessionItem(next, event.item, 0);
+    else if (event.output_index !== null) next = projectSessionItem(next, event.item, event.output_index);
   } else if (event.type === "agent.session.turn.output_text.delta") {
     if (!next.textMessages.some((message) => message.id === event.item_id)) throw new Error("Text delta has no message");
     const messages = next.textMessages.map((message) => message.id === event.item_id ? { ...message, text: message.text + event.delta } : message);
@@ -167,6 +168,7 @@ function useAgentSession(options) {
   const [error, setError] = useState(null);
   const [sessionId, setSessionId] = useState(options.initialSessionId ?? null);
   const [artifacts, setArtifacts] = useState([]);
+  const [requiredActions, setRequiredActions] = useState([]);
   const idRef = useRef(sessionId);
   const creating = useRef(null);
   const active = useRef(null);
@@ -207,7 +209,7 @@ function useAgentSession(options) {
         if (item.type === "message" && item.role === "user" && item.id !== null) restored.push({ id: item.id, role: "user", content: item.content.filter((part) => part.type === "input_text").map((part) => part.text).join("\n"), status: "completed", turnId: null, projection: null });
       }
       const projection = sessionItemState(turnItems);
-      restored.push({ id: turn.id, role: "assistant", content: projection.textMessages.map((item) => item.text).join("\n\n"), status: turn.status === "failed" ? "failed" : turn.status === "cancelled" ? "cancelled" : turn.status === "completed" ? "completed" : "streaming", turnId: turn.id, projection: { ...projection, turnId: turn.id } });
+      restored.push({ id: turn.id, role: "assistant", content: projection.textMessages.map((item) => item.text).join("\n\n"), status: turn.status === "failed" ? "failed" : turn.status === "cancelled" ? "cancelled" : turn.status === "completed" ? "completed" : turn.status === "waiting" ? "waiting" : "streaming", turnId: turn.id, projection: { ...projection, turnId: turn.id } });
     }
     setMessages((previous) => restored.map((message) => {
       const existing = previous.find((value) => value.turnId !== null && value.turnId === message.turnId);
@@ -217,7 +219,9 @@ function useAgentSession(options) {
   }, [transport]);
   useEffect(() => {
     const id = initial.current;
-    if (!id) return;
+    if (!id) return () => {
+      active.current?.abort();
+    };
     let cancelled = false;
     busy.current = true;
     setStatus("streaming");
@@ -225,11 +229,13 @@ function useAgentSession(options) {
       await refresh(id);
       while (!cancelled) {
         const session = await transport.retrieve(id);
-        if (session.status !== "in_progress") {
+        if (cancelled) return;
+        setRequiredActions(session.required_actions);
+        if (session.status !== "in_progress" && session.status !== "requires_action") {
           if (session.status === "failed") throw new Error(session.error ?? "Session failed");
-          if (session.status === "requires_action") throw new Error("Session is waiting for a client tool result");
           break;
         }
+        setStatus(session.status === "requires_action" ? "requires_action" : "streaming");
         await new Promise((resolve) => setTimeout(resolve, 1e3));
         if (!cancelled) await refresh(id);
       }
@@ -256,6 +262,7 @@ function useAgentSession(options) {
     submitted.current = false;
     setStatus("streaming");
     setError(null);
+    setRequiredActions([]);
     const abort = new AbortController();
     active.current = abort;
     const assistantId = crypto.randomUUID();
@@ -289,12 +296,18 @@ function useAgentSession(options) {
         setMessages((previous) => previous.map((message) => message.id === assistantId ? { ...message, content: projection.textMessages.map((item) => item.text).join("\n\n"), turnId: projection.turnId, projection } : message));
         if (event.type === "agent.session.turn.completed" || event.type === "agent.session.turn.cancelled" || event.type === "agent.session.turn.failed") {
           await refresh(id);
+          setRequiredActions([]);
           if (event.type === "agent.session.turn.failed") throw new Error(event.turn.error?.message ?? "Turn failed");
           setStatus("idle");
           return event.turn;
         }
         if (event.type === "agent.session.failed") throw new Error(event.session.error ?? "Session failed");
-        if (event.type === "agent.session.requires_action") throw new Error("Session is waiting for a client tool result");
+        if (event.type === "agent.session.requires_action" || event.type === "agent.session.in_progress") {
+          const waiting = event.type === "agent.session.requires_action";
+          setRequiredActions(event.session.required_actions);
+          setStatus(waiting ? "requires_action" : "streaming");
+          setMessages((previous) => previous.map((message) => message.id === assistantId ? { ...message, status: waiting ? "waiting" : "streaming" } : message));
+        }
         if (event.type === "error") throw new Error(event.error.message);
       }
       throw new Error("Session event stream disconnected. Reload to recover persisted output.");
@@ -320,12 +333,26 @@ function useAgentSession(options) {
       throw fail(cause);
     }
   }, [transport, fail]);
+  const submitToolResult = useCallback(async (result) => {
+    const id = idRef.current;
+    if (!id) throw new Error("No Session is waiting for a function result");
+    setError(null);
+    try {
+      await transport.submit(id, [{ type: "agent.session.input.tool_result", ...result }], `agent-result:${result.turn_id}:${result.call_id}`);
+    } catch (cause) {
+      const failure = cause instanceof Error ? cause : new Error(String(cause));
+      setError(failure);
+      throw failure;
+    }
+  }, [transport]);
   return {
     messages,
     status,
     error,
     sessionId,
     artifacts,
+    requiredActions,
+    submitToolResult,
     send,
     stop,
     async upload(file, progress) {
@@ -340,6 +367,7 @@ function useAgentSession(options) {
       setSessionId(null);
       setMessages([]);
       setArtifacts([]);
+      setRequiredActions([]);
       setError(null);
       setStatus("idle");
       onSession?.(null);

package/package.json

@@ -1,15 +1,15 @@
 {
   "name": "@rebyteai/agent-react",
-  "version": "0.3.0",
+  "version": "0.6.0",
   "description": "Headless React hooks and transports for Rebyte Agents",
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/ReByteAI/rebyte-agent-toolkit.git",
+    "url": "git+https://github.com/ReByteAI/rebyte-agent-sdk.git",
     "directory": "packages/react"
   },
-  "homepage": "https://github.com/ReByteAI/rebyte-agent-toolkit#readme",
-  "bugs": "https://github.com/ReByteAI/rebyte-agent-toolkit/issues",
+  "homepage": "https://github.com/ReByteAI/rebyte-agent-sdk#readme",
+  "bugs": "https://github.com/ReByteAI/rebyte-agent-sdk/issues",
   "engines": {
     "node": ">=22"
   },