@rebyteai/agent-react 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Rebyte, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,40 @@
+# @rebyteai/agent-react
+
+Install the versioned package (no repository clone required):
+
+```sh
+pnpm add @rebyteai/agent-react@0.2.0
+```
+
+
+Headless React state for native Agents API Sessions. The browser calls your
+same-origin application server, never the organization API directly.
+
+```tsx
+import { createAgentSessionTransport, useAgentSession } from '@rebyteai/agent-react'
+const transport = createAgentSessionTransport({ url: '/api/sessions' })
+// Inside a React component:
+const chat = useAgentSession({ transport, initialSessionId, onSession })
+```
+
+Persist `chat.sessionId` via `onSession`, then pass it as `initialSessionId` on
+reload. `send(text)` subscribes before posting input and resolves with a Turn.
+`stop()` submits cancellation; the running send consumes the terminal event.
+`reset()` starts a new conversation without deleting the old Session.
+`upload(file)` creates the Session if needed and writes a file into its environment
+(5 MiB maximum in this example). `artifacts` supplies immutable download URLs.
+
+Each assistant message has a `turnId` and a presentation-only `projection`:
+`textMessages`, `toolCalls`, `outputText`, and the received native `events`.
+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 [Rebyte SDK recipe](../../examples/agents-api/README.md) or Commerce adapter.
+
+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
+transport includes an organization API key.

package/dist/index.cjs

@@ -0,0 +1,382 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  AgentTransportError: () => AgentTransportError,
+  createAgentSessionTransport: () => createAgentSessionTransport,
+  useAgentSession: () => useAgentSession
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/state.ts
+var AgentTransportError = class extends Error {
+  status;
+  code;
+  body;
+  constructor(status, message, code, body) {
+    super(message);
+    this.name = "AgentTransportError";
+    this.status = status;
+    this.code = code;
+    this.body = body;
+  }
+};
+function createTurnState() {
+  return {
+    status: "idle",
+    turnId: null,
+    outputText: "",
+    textMessages: [],
+    error: null,
+    toolCalls: [],
+    events: []
+  };
+}
+
+// src/sessions.ts
+var import_streaming = require("@rebyteai/agent-sdk/core/streaming");
+function createAgentSessionTransport(options) {
+  const base = options.url.replace(/\/$/, "");
+  const request = options.fetch ?? globalThis.fetch;
+  async function checked(path2, init) {
+    const response = await request(`${base}${path2}`, init);
+    if (!response.ok) {
+      const body = await response.text();
+      let message = body;
+      try {
+        const parsed = JSON.parse(body);
+        if (typeof parsed?.error?.message === "string") message = parsed.error.message;
+      } catch {
+      }
+      throw new AgentTransportError(response.status, message, null, body);
+    }
+    return response;
+  }
+  const path = (id) => `/${encodeURIComponent(id)}`;
+  async function list(id, resource) {
+    return (await (await checked(`${path(id)}/${resource}`)).json()).data;
+  }
+  return {
+    async create() {
+      return (await checked("", { method: "POST" })).json();
+    },
+    async retrieve(id) {
+      return (await checked(path(id))).json();
+    },
+    async subscribe(id, signal) {
+      const controller = new AbortController();
+      const abort = () => controller.abort();
+      signal.addEventListener("abort", abort, { once: true });
+      if (signal.aborted) controller.abort();
+      let response;
+      try {
+        response = await checked(`${path(id)}/events`, { headers: { Accept: "text/event-stream" }, signal: controller.signal });
+      } catch (error) {
+        signal.removeEventListener("abort", abort);
+        throw error;
+      }
+      const stream = import_streaming.Stream.fromSSEResponse(response, controller);
+      return (async function* () {
+        try {
+          for await (const event of stream) yield event;
+        } finally {
+          signal.removeEventListener("abort", abort);
+          controller.abort();
+        }
+      })();
+    },
+    async submit(id, events, key) {
+      await checked(`${path(id)}/events`, { method: "POST", headers: { "Content-Type": "application/json", "Idempotency-Key": key }, body: JSON.stringify({ events }) });
+    },
+    items: (id) => list(id, "items"),
+    turns: (id) => list(id, "turns"),
+    artifacts: (id) => list(id, "artifacts"),
+    artifactURL: (id, artifactId) => `${base}${path(id)}/artifacts/${encodeURIComponent(artifactId)}/content`,
+    async upload(id, file, progress) {
+      if (file.size > 5 * 1024 * 1024) throw new Error("File exceeds the 5 MiB upload limit");
+      const url = `${base}${path(id)}/files?filename=${encodeURIComponent(file.name)}`;
+      const uploaded = await new Promise((resolve, reject) => {
+        const xhr = new XMLHttpRequest();
+        xhr.open("POST", url);
+        xhr.setRequestHeader("Content-Type", file.type || "application/octet-stream");
+        xhr.upload.onprogress = (e) => {
+          if (e.lengthComputable) progress?.({ loaded: e.loaded, total: e.total, percent: Math.min(99, Math.round(e.loaded / e.total * 100)) });
+        };
+        xhr.onload = () => {
+          try {
+            const body = JSON.parse(xhr.responseText);
+            if (xhr.status < 200 || xhr.status >= 300) throw new Error(body.error?.message ?? `Upload failed: ${xhr.status}`);
+            resolve(body);
+          } catch (error) {
+            reject(error);
+          }
+        };
+        xhr.onerror = () => reject(new Error("Upload failed"));
+        xhr.onabort = () => reject(new Error("Upload cancelled"));
+        xhr.send(file);
+      });
+      if (uploaded.session_id !== id || typeof uploaded.path !== "string" || uploaded.size_bytes !== file.size) throw new Error("Upload returned an invalid Session file");
+      progress?.({ loaded: file.size, total: file.size, percent: 100 });
+      return { sessionId: id, path: uploaded.path, fileId: uploaded.path, filename: file.name, size: file.size, contentType: file.type || "application/octet-stream", inputType: file.type.startsWith("image/") ? "input_image" : "input_file" };
+    }
+  };
+}
+function projectSessionItem(state, item, index) {
+  if (item.type === "message" && item.role === "assistant") {
+    if (item.id === null) throw new Error("Persisted assistant message has no ID");
+    const value2 = {
+      id: item.id,
+      outputIndex: index,
+      status: item.status,
+      phase: item.phase,
+      text: item.content.filter((part) => part.type === "output_text").map((part) => part.text).join("")
+    };
+    const messages = state.textMessages.some((message) => message.id === item.id) ? state.textMessages.map((message) => message.id === item.id ? value2 : message) : [...state.textMessages, value2];
+    return { ...state, textMessages: messages, outputText: messages.map((message) => message.text).join("") };
+  }
+  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 value = {
+    id: item.id,
+    outputIndex: index,
+    execution: item.type === "function_call" && !serverFunction ? "client" : "server",
+    callId: item.type === "function_call" ? item.call_id : null,
+    name: item.type === "command_execution" ? "exec_command" : item.name,
+    serverLabel: item.type === "command_execution" ? "Session Sandbox" : item.type === "mcp_call" ? item.server_label : serverFunction ? "Session runtime" : "client",
+    status: item.type === "function_call" && !serverFunction && item.status === "completed" ? "awaiting_output" : item.status,
+    arguments: item.type === "command_execution" ? item.command : JSON.stringify(item.arguments),
+    output: item.type === "command_execution" ? item.output : item.type === "mcp_call" && item.output != null ? JSON.stringify(item.output) : null,
+    error: item.type === "command_execution" && item.exit_code !== null && item.exit_code !== 0 ? `Exit code ${item.exit_code}` : item.type === "mcp_call" && item.error != null ? JSON.stringify(item.error) : null
+  };
+  return { ...state, toolCalls: state.toolCalls.some((tool) => tool.id === item.id) ? state.toolCalls.map((tool) => tool.id === item.id ? value : tool) : [...state.toolCalls, value] };
+}
+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);
+  } 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);
+    next = { ...next, textMessages: messages, outputText: messages.map((message) => message.text).join("") };
+  } else if (event.type === "agent.output.command_execution_output.delta") {
+    next.toolCalls = next.toolCalls.map((tool) => tool.id === event.item_id ? { ...tool, output: (tool.output ?? "") + event.delta } : tool);
+  }
+  return next;
+}
+function sessionItemState(items) {
+  return items.reduce((state, item, index) => projectSessionItem(state, item, index), createTurnState());
+}
+
+// src/use-agent-session.ts
+var import_react = require("react");
+function useAgentSession(options) {
+  const { transport, onSession } = options;
+  const [messages, setMessages] = (0, import_react.useState)([]);
+  const [status, setStatus] = (0, import_react.useState)("idle");
+  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 idRef = (0, import_react.useRef)(sessionId);
+  const creating = (0, import_react.useRef)(null);
+  const active = (0, import_react.useRef)(null);
+  const cancelRequested = (0, import_react.useRef)(false);
+  const submitted = (0, import_react.useRef)(false);
+  const generation = (0, import_react.useRef)(0);
+  const busy = (0, import_react.useRef)(false);
+  const initial = (0, import_react.useRef)(options.initialSessionId);
+  const fail = (0, import_react.useCallback)((cause) => {
+    const failure = cause instanceof Error ? cause : new Error(String(cause));
+    setError(failure);
+    setStatus("error");
+    return failure;
+  }, []);
+  const ensure = (0, import_react.useCallback)(async () => {
+    if (idRef.current) return idRef.current;
+    const currentGeneration = generation.current;
+    const pending = creating.current ?? transport.create();
+    creating.current = pending;
+    try {
+      const session = await pending;
+      if (generation.current !== currentGeneration) throw new Error("Conversation changed during Session creation");
+      idRef.current = session.id;
+      setSessionId(session.id);
+      onSession?.(session.id);
+      return session.id;
+    } finally {
+      if (creating.current === pending) creating.current = null;
+    }
+  }, [transport, onSession]);
+  const refresh = (0, import_react.useCallback)(async (id) => {
+    const [items, turns, outputs] = await Promise.all([transport.items(id), transport.turns(id), transport.artifacts(id)]);
+    if (idRef.current !== id) return;
+    const restored = [];
+    for (const turn of turns) {
+      const turnItems = items.filter((item) => item.turn_id === turn.id);
+      for (const item of turnItems) {
+        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 } });
+    }
+    setMessages((previous) => restored.map((message) => {
+      const existing = previous.find((value) => value.turnId !== null && value.turnId === message.turnId);
+      return existing?.projection && message.projection ? { ...message, projection: { ...message.projection, events: existing.projection.events } } : message;
+    }));
+    setArtifacts(outputs.map((artifact) => ({ ...artifact, url: transport.artifactURL(id, artifact.id) })));
+  }, [transport]);
+  (0, import_react.useEffect)(() => {
+    const id = initial.current;
+    if (!id) return;
+    let cancelled = false;
+    busy.current = true;
+    setStatus("streaming");
+    void (async () => {
+      await refresh(id);
+      while (!cancelled) {
+        const session = await transport.retrieve(id);
+        if (session.status !== "in_progress") {
+          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;
+        }
+        await new Promise((resolve) => setTimeout(resolve, 1e3));
+        if (!cancelled) await refresh(id);
+      }
+      if (!cancelled) {
+        await refresh(id);
+        setStatus("idle");
+      }
+    })().catch((cause) => {
+      if (!cancelled) fail(cause);
+    }).finally(() => {
+      if (!cancelled) busy.current = false;
+    });
+    return () => {
+      cancelled = true;
+      active.current?.abort();
+    };
+  }, [transport, refresh, fail]);
+  const send = (0, import_react.useCallback)(async (value) => {
+    if (busy.current) throw new Error("A turn is already running");
+    const input = typeof value === "string" ? { text: value, attachments: [] } : value;
+    if (!input.text.trim() && !input.attachments.length) throw new Error("Input is required");
+    busy.current = true;
+    cancelRequested.current = false;
+    submitted.current = false;
+    setStatus("streaming");
+    setError(null);
+    const abort = new AbortController();
+    active.current = abort;
+    const assistantId = crypto.randomUUID();
+    let projection = createTurnState();
+    let id = null;
+    try {
+      id = await ensure();
+      abort.signal.throwIfAborted();
+      if (cancelRequested.current) {
+        setStatus("idle");
+        return null;
+      }
+      const text = [input.text.trim(), ...input.attachments.map((file) => {
+        if (!("sessionId" in file) || file.sessionId !== id || !("path" in file) || typeof file.path !== "string") throw new Error("Attachment belongs to another Session");
+        return `Attached file: ${JSON.stringify(file.path)}. Read this file in your Session environment.`;
+      })].filter(Boolean).join("\n");
+      setMessages((previous) => [...previous, { id: crypto.randomUUID(), role: "user", content: input.text, attachments: input.attachments, status: "completed", turnId: null, projection: null }, { id: assistantId, role: "assistant", content: "", status: "streaming", turnId: null, projection }]);
+      const events = await transport.subscribe(id, abort.signal);
+      abort.signal.throwIfAborted();
+      if (cancelRequested.current) {
+        setStatus("idle");
+        return null;
+      }
+      await transport.submit(id, [{ type: "agent.session.input.message", input: [{ role: "user", content: [{ type: "input_text", text }] }] }], crypto.randomUUID());
+      submitted.current = true;
+      if (cancelRequested.current) await transport.submit(id, [{ type: "agent.session.input.cancel" }], crypto.randomUUID());
+      for await (const event of events) {
+        if ("session_id" in event && event.session_id !== id) throw new Error("Event belongs to another Session");
+        projection = reduceSessionEvent(projection, event);
+        if ("turn_id" in event && typeof event.turn_id === "string") projection = { ...projection, turnId: event.turn_id };
+        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);
+          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 === "error") throw new Error(event.error.message);
+      }
+      throw new Error("Session event stream disconnected. Reload to recover persisted output.");
+    } catch (cause) {
+      if (abort.signal.aborted) {
+        if (id) await refresh(id);
+        setStatus("idle");
+        return null;
+      }
+      throw fail(cause);
+    } finally {
+      abort.abort();
+      if (active.current === abort) active.current = null;
+      busy.current = false;
+    }
+  }, [ensure, fail, refresh, transport]);
+  const stop = (0, import_react.useCallback)(async () => {
+    const id = idRef.current;
+    cancelRequested.current = true;
+    try {
+      if (id && (submitted.current || active.current === null)) await transport.submit(id, [{ type: "agent.session.input.cancel" }], crypto.randomUUID());
+    } catch (cause) {
+      throw fail(cause);
+    }
+  }, [transport, fail]);
+  return {
+    messages,
+    status,
+    error,
+    sessionId,
+    artifacts,
+    send,
+    stop,
+    async upload(file, progress) {
+      const id = await ensure();
+      return transport.upload(id, file, progress);
+    },
+    reset() {
+      if (busy.current) throw new Error("Stop the active turn before starting a new Session");
+      generation.current++;
+      idRef.current = null;
+      creating.current = null;
+      setSessionId(null);
+      setMessages([]);
+      setArtifacts([]);
+      setError(null);
+      setStatus("idle");
+      onSession?.(null);
+    }
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  AgentTransportError,
+  createAgentSessionTransport,
+  useAgentSession
+});

package/dist/index.d.cts

@@ -0,0 +1,107 @@
+import { AgentSessionEvent, AgentSession, AgentSessionInputParam, AgentSessionItem } from '@rebyteai/agent-sdk/resources/beta/agents/agents';
+export { AgentSession, AgentSessionEvent } from '@rebyteai/agent-sdk/resources/beta/agents/agents';
+import { Turn } from '@rebyteai/agent-sdk/resources/beta/agents/sessions/turns';
+export { Turn } from '@rebyteai/agent-sdk/resources/beta/agents/sessions/turns';
+import { SessionArtifact } from '@rebyteai/agent-sdk/resources/beta/agents/sessions/artifacts';
+export { SessionArtifact } from '@rebyteai/agent-sdk/resources/beta/agents/sessions/artifacts';
+
+interface AgentAttachment {
+    fileId: string;
+    filename: string;
+    contentType: string;
+    size: number;
+    inputType: 'input_file' | 'input_image';
+}
+interface AgentChatInput {
+    text: string;
+    attachments: AgentAttachment[];
+}
+interface AgentUploadProgress {
+    loaded: number;
+    total: number;
+    percent: number;
+}
+interface ToolCallState {
+    id: string;
+    outputIndex: number;
+    execution: 'server' | 'client';
+    callId: string | null;
+    name: string;
+    serverLabel: string;
+    status: 'in_progress' | 'completed' | 'incomplete' | 'failed' | 'awaiting_output';
+    arguments: string;
+    output: string | null;
+    error: string | null;
+}
+interface TextMessageState {
+    id: string;
+    outputIndex: number;
+    text: string;
+    phase: 'commentary' | 'final_answer' | null;
+    status: 'in_progress' | 'completed' | 'incomplete';
+}
+interface TurnState {
+    status: 'idle' | 'in_progress' | 'completed' | 'failed';
+    turnId: string | null;
+    outputText: string;
+    textMessages: TextMessageState[];
+    error: string | null;
+    toolCalls: ToolCallState[];
+    events: AgentSessionEvent[];
+}
+declare class AgentTransportError extends Error {
+    readonly status: number;
+    readonly code: string | null;
+    readonly body: unknown;
+    constructor(status: number, message: string, code: string | null, body: unknown);
+}
+interface AgentChatMessage {
+    id: string;
+    role: 'user' | 'assistant';
+    content: string;
+    attachments?: AgentAttachment[];
+    status: 'completed' | 'streaming' | 'failed' | 'cancelled';
+    turnId: string | null;
+    projection: TurnState | null;
+}
+
+interface SessionAttachment extends AgentAttachment {
+    sessionId: string;
+    path: string;
+}
+interface AgentSessionTransport {
+    create(): Promise<AgentSession>;
+    retrieve(id: string): Promise<AgentSession>;
+    subscribe(id: string, signal: AbortSignal): Promise<AsyncIterable<AgentSessionEvent>>;
+    submit(id: string, events: AgentSessionInputParam[], key: string): Promise<void>;
+    items(id: string): Promise<AgentSessionItem[]>;
+    turns(id: string): Promise<Turn[]>;
+    artifacts(id: string): Promise<SessionArtifact[]>;
+    artifactURL(sessionId: string, artifactId: string): string;
+    upload(id: string, file: File, progress?: (value: AgentUploadProgress) => void): Promise<SessionAttachment>;
+}
+declare function createAgentSessionTransport(options: {
+    url: string;
+    fetch?: typeof fetch;
+}): AgentSessionTransport;
+
+interface AgentSessionChat {
+    messages: AgentChatMessage[];
+    status: 'idle' | 'streaming' | 'error';
+    error: Error | null;
+    sessionId: string | null;
+    artifacts: Array<SessionArtifact & {
+        url: string;
+    }>;
+    send(input: string | AgentChatInput): Promise<Turn | null>;
+    upload(file: File, progress?: (value: AgentUploadProgress) => void): Promise<SessionAttachment>;
+    stop(): Promise<void>;
+    reset(): void;
+}
+declare function useAgentSession(options: {
+    transport: AgentSessionTransport;
+    initialSessionId?: string;
+    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 };

package/dist/index.d.ts

@@ -0,0 +1,107 @@
+import { AgentSessionEvent, AgentSession, AgentSessionInputParam, AgentSessionItem } from '@rebyteai/agent-sdk/resources/beta/agents/agents';
+export { AgentSession, AgentSessionEvent } from '@rebyteai/agent-sdk/resources/beta/agents/agents';
+import { Turn } from '@rebyteai/agent-sdk/resources/beta/agents/sessions/turns';
+export { Turn } from '@rebyteai/agent-sdk/resources/beta/agents/sessions/turns';
+import { SessionArtifact } from '@rebyteai/agent-sdk/resources/beta/agents/sessions/artifacts';
+export { SessionArtifact } from '@rebyteai/agent-sdk/resources/beta/agents/sessions/artifacts';
+
+interface AgentAttachment {
+    fileId: string;
+    filename: string;
+    contentType: string;
+    size: number;
+    inputType: 'input_file' | 'input_image';
+}
+interface AgentChatInput {
+    text: string;
+    attachments: AgentAttachment[];
+}
+interface AgentUploadProgress {
+    loaded: number;
+    total: number;
+    percent: number;
+}
+interface ToolCallState {
+    id: string;
+    outputIndex: number;
+    execution: 'server' | 'client';
+    callId: string | null;
+    name: string;
+    serverLabel: string;
+    status: 'in_progress' | 'completed' | 'incomplete' | 'failed' | 'awaiting_output';
+    arguments: string;
+    output: string | null;
+    error: string | null;
+}
+interface TextMessageState {
+    id: string;
+    outputIndex: number;
+    text: string;
+    phase: 'commentary' | 'final_answer' | null;
+    status: 'in_progress' | 'completed' | 'incomplete';
+}
+interface TurnState {
+    status: 'idle' | 'in_progress' | 'completed' | 'failed';
+    turnId: string | null;
+    outputText: string;
+    textMessages: TextMessageState[];
+    error: string | null;
+    toolCalls: ToolCallState[];
+    events: AgentSessionEvent[];
+}
+declare class AgentTransportError extends Error {
+    readonly status: number;
+    readonly code: string | null;
+    readonly body: unknown;
+    constructor(status: number, message: string, code: string | null, body: unknown);
+}
+interface AgentChatMessage {
+    id: string;
+    role: 'user' | 'assistant';
+    content: string;
+    attachments?: AgentAttachment[];
+    status: 'completed' | 'streaming' | 'failed' | 'cancelled';
+    turnId: string | null;
+    projection: TurnState | null;
+}
+
+interface SessionAttachment extends AgentAttachment {
+    sessionId: string;
+    path: string;
+}
+interface AgentSessionTransport {
+    create(): Promise<AgentSession>;
+    retrieve(id: string): Promise<AgentSession>;
+    subscribe(id: string, signal: AbortSignal): Promise<AsyncIterable<AgentSessionEvent>>;
+    submit(id: string, events: AgentSessionInputParam[], key: string): Promise<void>;
+    items(id: string): Promise<AgentSessionItem[]>;
+    turns(id: string): Promise<Turn[]>;
+    artifacts(id: string): Promise<SessionArtifact[]>;
+    artifactURL(sessionId: string, artifactId: string): string;
+    upload(id: string, file: File, progress?: (value: AgentUploadProgress) => void): Promise<SessionAttachment>;
+}
+declare function createAgentSessionTransport(options: {
+    url: string;
+    fetch?: typeof fetch;
+}): AgentSessionTransport;
+
+interface AgentSessionChat {
+    messages: AgentChatMessage[];
+    status: 'idle' | 'streaming' | 'error';
+    error: Error | null;
+    sessionId: string | null;
+    artifacts: Array<SessionArtifact & {
+        url: string;
+    }>;
+    send(input: string | AgentChatInput): Promise<Turn | null>;
+    upload(file: File, progress?: (value: AgentUploadProgress) => void): Promise<SessionAttachment>;
+    stop(): Promise<void>;
+    reset(): void;
+}
+declare function useAgentSession(options: {
+    transport: AgentSessionTransport;
+    initialSessionId?: string;
+    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 };

package/dist/index.js

@@ -0,0 +1,353 @@
+// src/state.ts
+var AgentTransportError = class extends Error {
+  status;
+  code;
+  body;
+  constructor(status, message, code, body) {
+    super(message);
+    this.name = "AgentTransportError";
+    this.status = status;
+    this.code = code;
+    this.body = body;
+  }
+};
+function createTurnState() {
+  return {
+    status: "idle",
+    turnId: null,
+    outputText: "",
+    textMessages: [],
+    error: null,
+    toolCalls: [],
+    events: []
+  };
+}
+
+// src/sessions.ts
+import { Stream } from "@rebyteai/agent-sdk/core/streaming";
+function createAgentSessionTransport(options) {
+  const base = options.url.replace(/\/$/, "");
+  const request = options.fetch ?? globalThis.fetch;
+  async function checked(path2, init) {
+    const response = await request(`${base}${path2}`, init);
+    if (!response.ok) {
+      const body = await response.text();
+      let message = body;
+      try {
+        const parsed = JSON.parse(body);
+        if (typeof parsed?.error?.message === "string") message = parsed.error.message;
+      } catch {
+      }
+      throw new AgentTransportError(response.status, message, null, body);
+    }
+    return response;
+  }
+  const path = (id) => `/${encodeURIComponent(id)}`;
+  async function list(id, resource) {
+    return (await (await checked(`${path(id)}/${resource}`)).json()).data;
+  }
+  return {
+    async create() {
+      return (await checked("", { method: "POST" })).json();
+    },
+    async retrieve(id) {
+      return (await checked(path(id))).json();
+    },
+    async subscribe(id, signal) {
+      const controller = new AbortController();
+      const abort = () => controller.abort();
+      signal.addEventListener("abort", abort, { once: true });
+      if (signal.aborted) controller.abort();
+      let response;
+      try {
+        response = await checked(`${path(id)}/events`, { headers: { Accept: "text/event-stream" }, signal: controller.signal });
+      } catch (error) {
+        signal.removeEventListener("abort", abort);
+        throw error;
+      }
+      const stream = Stream.fromSSEResponse(response, controller);
+      return (async function* () {
+        try {
+          for await (const event of stream) yield event;
+        } finally {
+          signal.removeEventListener("abort", abort);
+          controller.abort();
+        }
+      })();
+    },
+    async submit(id, events, key) {
+      await checked(`${path(id)}/events`, { method: "POST", headers: { "Content-Type": "application/json", "Idempotency-Key": key }, body: JSON.stringify({ events }) });
+    },
+    items: (id) => list(id, "items"),
+    turns: (id) => list(id, "turns"),
+    artifacts: (id) => list(id, "artifacts"),
+    artifactURL: (id, artifactId) => `${base}${path(id)}/artifacts/${encodeURIComponent(artifactId)}/content`,
+    async upload(id, file, progress) {
+      if (file.size > 5 * 1024 * 1024) throw new Error("File exceeds the 5 MiB upload limit");
+      const url = `${base}${path(id)}/files?filename=${encodeURIComponent(file.name)}`;
+      const uploaded = await new Promise((resolve, reject) => {
+        const xhr = new XMLHttpRequest();
+        xhr.open("POST", url);
+        xhr.setRequestHeader("Content-Type", file.type || "application/octet-stream");
+        xhr.upload.onprogress = (e) => {
+          if (e.lengthComputable) progress?.({ loaded: e.loaded, total: e.total, percent: Math.min(99, Math.round(e.loaded / e.total * 100)) });
+        };
+        xhr.onload = () => {
+          try {
+            const body = JSON.parse(xhr.responseText);
+            if (xhr.status < 200 || xhr.status >= 300) throw new Error(body.error?.message ?? `Upload failed: ${xhr.status}`);
+            resolve(body);
+          } catch (error) {
+            reject(error);
+          }
+        };
+        xhr.onerror = () => reject(new Error("Upload failed"));
+        xhr.onabort = () => reject(new Error("Upload cancelled"));
+        xhr.send(file);
+      });
+      if (uploaded.session_id !== id || typeof uploaded.path !== "string" || uploaded.size_bytes !== file.size) throw new Error("Upload returned an invalid Session file");
+      progress?.({ loaded: file.size, total: file.size, percent: 100 });
+      return { sessionId: id, path: uploaded.path, fileId: uploaded.path, filename: file.name, size: file.size, contentType: file.type || "application/octet-stream", inputType: file.type.startsWith("image/") ? "input_image" : "input_file" };
+    }
+  };
+}
+function projectSessionItem(state, item, index) {
+  if (item.type === "message" && item.role === "assistant") {
+    if (item.id === null) throw new Error("Persisted assistant message has no ID");
+    const value2 = {
+      id: item.id,
+      outputIndex: index,
+      status: item.status,
+      phase: item.phase,
+      text: item.content.filter((part) => part.type === "output_text").map((part) => part.text).join("")
+    };
+    const messages = state.textMessages.some((message) => message.id === item.id) ? state.textMessages.map((message) => message.id === item.id ? value2 : message) : [...state.textMessages, value2];
+    return { ...state, textMessages: messages, outputText: messages.map((message) => message.text).join("") };
+  }
+  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 value = {
+    id: item.id,
+    outputIndex: index,
+    execution: item.type === "function_call" && !serverFunction ? "client" : "server",
+    callId: item.type === "function_call" ? item.call_id : null,
+    name: item.type === "command_execution" ? "exec_command" : item.name,
+    serverLabel: item.type === "command_execution" ? "Session Sandbox" : item.type === "mcp_call" ? item.server_label : serverFunction ? "Session runtime" : "client",
+    status: item.type === "function_call" && !serverFunction && item.status === "completed" ? "awaiting_output" : item.status,
+    arguments: item.type === "command_execution" ? item.command : JSON.stringify(item.arguments),
+    output: item.type === "command_execution" ? item.output : item.type === "mcp_call" && item.output != null ? JSON.stringify(item.output) : null,
+    error: item.type === "command_execution" && item.exit_code !== null && item.exit_code !== 0 ? `Exit code ${item.exit_code}` : item.type === "mcp_call" && item.error != null ? JSON.stringify(item.error) : null
+  };
+  return { ...state, toolCalls: state.toolCalls.some((tool) => tool.id === item.id) ? state.toolCalls.map((tool) => tool.id === item.id ? value : tool) : [...state.toolCalls, value] };
+}
+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);
+  } 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);
+    next = { ...next, textMessages: messages, outputText: messages.map((message) => message.text).join("") };
+  } else if (event.type === "agent.output.command_execution_output.delta") {
+    next.toolCalls = next.toolCalls.map((tool) => tool.id === event.item_id ? { ...tool, output: (tool.output ?? "") + event.delta } : tool);
+  }
+  return next;
+}
+function sessionItemState(items) {
+  return items.reduce((state, item, index) => projectSessionItem(state, item, index), createTurnState());
+}
+
+// src/use-agent-session.ts
+import { useCallback, useEffect, useRef, useState } from "react";
+function useAgentSession(options) {
+  const { transport, onSession } = options;
+  const [messages, setMessages] = useState([]);
+  const [status, setStatus] = useState("idle");
+  const [error, setError] = useState(null);
+  const [sessionId, setSessionId] = useState(options.initialSessionId ?? null);
+  const [artifacts, setArtifacts] = useState([]);
+  const idRef = useRef(sessionId);
+  const creating = useRef(null);
+  const active = useRef(null);
+  const cancelRequested = useRef(false);
+  const submitted = useRef(false);
+  const generation = useRef(0);
+  const busy = useRef(false);
+  const initial = useRef(options.initialSessionId);
+  const fail = useCallback((cause) => {
+    const failure = cause instanceof Error ? cause : new Error(String(cause));
+    setError(failure);
+    setStatus("error");
+    return failure;
+  }, []);
+  const ensure = useCallback(async () => {
+    if (idRef.current) return idRef.current;
+    const currentGeneration = generation.current;
+    const pending = creating.current ?? transport.create();
+    creating.current = pending;
+    try {
+      const session = await pending;
+      if (generation.current !== currentGeneration) throw new Error("Conversation changed during Session creation");
+      idRef.current = session.id;
+      setSessionId(session.id);
+      onSession?.(session.id);
+      return session.id;
+    } finally {
+      if (creating.current === pending) creating.current = null;
+    }
+  }, [transport, onSession]);
+  const refresh = useCallback(async (id) => {
+    const [items, turns, outputs] = await Promise.all([transport.items(id), transport.turns(id), transport.artifacts(id)]);
+    if (idRef.current !== id) return;
+    const restored = [];
+    for (const turn of turns) {
+      const turnItems = items.filter((item) => item.turn_id === turn.id);
+      for (const item of turnItems) {
+        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 } });
+    }
+    setMessages((previous) => restored.map((message) => {
+      const existing = previous.find((value) => value.turnId !== null && value.turnId === message.turnId);
+      return existing?.projection && message.projection ? { ...message, projection: { ...message.projection, events: existing.projection.events } } : message;
+    }));
+    setArtifacts(outputs.map((artifact) => ({ ...artifact, url: transport.artifactURL(id, artifact.id) })));
+  }, [transport]);
+  useEffect(() => {
+    const id = initial.current;
+    if (!id) return;
+    let cancelled = false;
+    busy.current = true;
+    setStatus("streaming");
+    void (async () => {
+      await refresh(id);
+      while (!cancelled) {
+        const session = await transport.retrieve(id);
+        if (session.status !== "in_progress") {
+          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;
+        }
+        await new Promise((resolve) => setTimeout(resolve, 1e3));
+        if (!cancelled) await refresh(id);
+      }
+      if (!cancelled) {
+        await refresh(id);
+        setStatus("idle");
+      }
+    })().catch((cause) => {
+      if (!cancelled) fail(cause);
+    }).finally(() => {
+      if (!cancelled) busy.current = false;
+    });
+    return () => {
+      cancelled = true;
+      active.current?.abort();
+    };
+  }, [transport, refresh, fail]);
+  const send = useCallback(async (value) => {
+    if (busy.current) throw new Error("A turn is already running");
+    const input = typeof value === "string" ? { text: value, attachments: [] } : value;
+    if (!input.text.trim() && !input.attachments.length) throw new Error("Input is required");
+    busy.current = true;
+    cancelRequested.current = false;
+    submitted.current = false;
+    setStatus("streaming");
+    setError(null);
+    const abort = new AbortController();
+    active.current = abort;
+    const assistantId = crypto.randomUUID();
+    let projection = createTurnState();
+    let id = null;
+    try {
+      id = await ensure();
+      abort.signal.throwIfAborted();
+      if (cancelRequested.current) {
+        setStatus("idle");
+        return null;
+      }
+      const text = [input.text.trim(), ...input.attachments.map((file) => {
+        if (!("sessionId" in file) || file.sessionId !== id || !("path" in file) || typeof file.path !== "string") throw new Error("Attachment belongs to another Session");
+        return `Attached file: ${JSON.stringify(file.path)}. Read this file in your Session environment.`;
+      })].filter(Boolean).join("\n");
+      setMessages((previous) => [...previous, { id: crypto.randomUUID(), role: "user", content: input.text, attachments: input.attachments, status: "completed", turnId: null, projection: null }, { id: assistantId, role: "assistant", content: "", status: "streaming", turnId: null, projection }]);
+      const events = await transport.subscribe(id, abort.signal);
+      abort.signal.throwIfAborted();
+      if (cancelRequested.current) {
+        setStatus("idle");
+        return null;
+      }
+      await transport.submit(id, [{ type: "agent.session.input.message", input: [{ role: "user", content: [{ type: "input_text", text }] }] }], crypto.randomUUID());
+      submitted.current = true;
+      if (cancelRequested.current) await transport.submit(id, [{ type: "agent.session.input.cancel" }], crypto.randomUUID());
+      for await (const event of events) {
+        if ("session_id" in event && event.session_id !== id) throw new Error("Event belongs to another Session");
+        projection = reduceSessionEvent(projection, event);
+        if ("turn_id" in event && typeof event.turn_id === "string") projection = { ...projection, turnId: event.turn_id };
+        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);
+          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 === "error") throw new Error(event.error.message);
+      }
+      throw new Error("Session event stream disconnected. Reload to recover persisted output.");
+    } catch (cause) {
+      if (abort.signal.aborted) {
+        if (id) await refresh(id);
+        setStatus("idle");
+        return null;
+      }
+      throw fail(cause);
+    } finally {
+      abort.abort();
+      if (active.current === abort) active.current = null;
+      busy.current = false;
+    }
+  }, [ensure, fail, refresh, transport]);
+  const stop = useCallback(async () => {
+    const id = idRef.current;
+    cancelRequested.current = true;
+    try {
+      if (id && (submitted.current || active.current === null)) await transport.submit(id, [{ type: "agent.session.input.cancel" }], crypto.randomUUID());
+    } catch (cause) {
+      throw fail(cause);
+    }
+  }, [transport, fail]);
+  return {
+    messages,
+    status,
+    error,
+    sessionId,
+    artifacts,
+    send,
+    stop,
+    async upload(file, progress) {
+      const id = await ensure();
+      return transport.upload(id, file, progress);
+    },
+    reset() {
+      if (busy.current) throw new Error("Stop the active turn before starting a new Session");
+      generation.current++;
+      idRef.current = null;
+      creating.current = null;
+      setSessionId(null);
+      setMessages([]);
+      setArtifacts([]);
+      setError(null);
+      setStatus("idle");
+      onSession?.(null);
+    }
+  };
+}
+export {
+  AgentTransportError,
+  createAgentSessionTransport,
+  useAgentSession
+};

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@rebyteai/agent-react",
+  "version": "0.2.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",
+    "directory": "packages/react"
+  },
+  "homepage": "https://github.com/ReByteAI/rebyte-agent-toolkit#readme",
+  "bugs": "https://github.com/ReByteAI/rebyte-agent-toolkit/issues",
+  "engines": {
+    "node": ">=22"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  },
+  "peerDependencies": {
+    "react": ">=18.2.0"
+  },
+  "devDependencies": {
+    "@types/react": "^19.2.0",
+    "react": "^19.2.0",
+    "tsup": "^8.5.0",
+    "typescript": "^5.9.3"
+  },
+  "dependencies": {
+    "@rebyteai/agent-sdk": "0.2.0"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format esm,cjs --dts --clean --external react",
+    "typecheck": "tsc --noEmit"
+  }
+}