@standardagents/react

import {
  AgentBuilderProvider,
  ThreadProvider,
  useThread,
} from "@standardagents/react"

function App() {
  return (
    <AgentBuilderProvider config={{ endpoint: "https://your-api.com" }}>
      <ThreadProvider threadId="123e4567-e89b-12d3-a456-426614174000">
        <ChatInterface />
      </ThreadProvider>
    </AgentBuilderProvider>
  )
}

function ChatInterface() {
  const { messages, sendMessage, status } = useThread()

  const handleSend = async (text: string) => {
    await sendMessage({ role: "user", content: text })
  }

  return (
    <div>
      <p>Status: {status}</p>
      {messages.map((msg) => (
        <div key={msg.id}>
          <strong>{msg.role}:</strong> {msg.content}
        </div>
      ))}
      <input onKeyDown={(e) => e.key === "Enter" && handleSend(e.currentTarget.value)} />
    </div>
  )
}

<AgentBuilderProvider config={{ endpoint: "https://api.example.com" }}>
  {children}
</AgentBuilderProvider>

<ThreadProvider
  threadId="123e4567-e89b-12d3-a456-426614174000"
  preload={true}
  live={true}
  useWorkblocks={false}
  depth={0}
  includeSilent={false}
>
  <ChatInterface />
</ThreadProvider>

import { useThread } from "@standardagents/react"

function ChatMessages() {
  const {
    // Messages & State
    messages,
    workblocks,
    loading,
    error,
    status,

    // Actions
    sendMessage,
    stopExecution,
    deleteMessage,

    // Custom Events
    onEvent,

    // File Management (uploads to filesystem)
    files,
    addFiles,
    removeFile,
    getFileUrl,
    getPreviewUrl,

    // Attachment Management (sent to LLM)
    attachments,
    addAttachment,
    removeAttachment,
    clearAttachments,
  } = useThread()

  return (
    <div>
      <p>Status: {status}</p>
      {loading && <p>Loading...</p>}
      {messages.map((msg) => (
        <MessageBubble key={msg.id} message={msg} />
      ))}
    </div>
  )
}

const { sendMessage, attachments } = useThread()

// Simple text message
await sendMessage({ role: 'user', content: 'Hello!' })

// With attachments (call addAttachment first)
// Attachments are auto-included and cleared after send
addAttachment(imageFile)
await sendMessage({ role: 'user', content: 'What is in this image?' })

sendMessage(payload: Omit<SendMessagePayload, 'attachments'>): Promise<Message>

interface SendMessagePayload {
  role: 'user' | 'assistant' | 'system'
  content: string
  silent?: boolean
}

const { addAttachment, attachments } = useThread()

// Single file
const handleFileSelect = (e: React.ChangeEvent<HTMLInputElement>) => {
  if (e.target.files?.[0]) {
    addAttachment(e.target.files[0])
  }
}

// Multiple files
addAttachment(Array.from(fileInput.files))

// FileList directly
addAttachment(e.target.files)

// Show previews for pending attachments
{attachments.map(a => (
  <div key={a.id}>
    {a.isImage && a.previewUrl && (
      <img src={a.previewUrl} alt={a.name} />
    )}
    <span>{a.name}</span>
    <button onClick={() => removeAttachment(a.id)}>Remove</button>
  </div>
))}

addAttachment(files: File | File[] | FileList): void

interface PendingAttachment {
  id: string              // Temporary ID
  file: File              // Original file object
  name: string
  mimeType: string
  size: number
  isImage: boolean
  previewUrl: string | null  // Object URL for image preview
  width?: number
  height?: number
}

const { removeAttachment, attachments } = useThread()

<button onClick={() => removeAttachment(attachment.id)}>Remove</button>

removeAttachment(id: string): void

const { clearAttachments, attachments } = useThread()

{attachments.length > 0 && (
  <button onClick={clearAttachments}>Clear All</button>
)}

clearAttachments(): void

const { addFiles, files, getPreviewUrl } = useThread()

// Upload files to filesystem
addFiles(fileInput.files)

// Display uploaded files
{files.map(f => (
  <div key={f.id}>
    {f.isImage && <img src={getPreviewUrl(f)} alt={f.name} />}
    <span>{f.name}</span>
    <span>{f.status}</span> {/* 'uploading' | 'ready' | 'committed' | 'error' */}
  </div>
))}

addFiles(files: File[] | FileList): void

interface ThreadFile {
  id: string
  name: string
  mimeType: string
  size: number
  isImage: boolean
  localPreviewUrl: string | null
  status: 'uploading' | 'ready' | 'committed' | 'error'
  error?: string
  path?: string
  width?: number
  height?: number
  messageId?: string
}

const { removeFile } = useThread()

<button onClick={() => removeFile(file.id)}>Cancel Upload</button>

const { getFileUrl, getThumbnailUrl, getPreviewUrl } = useThread()

// Full file URL (for download/viewing)
const url = getFileUrl(file)

// Thumbnail URL (for images)
const thumb = getThumbnailUrl(file)

// Preview URL (smart - uses local preview for pending, thumbnail for committed)
const preview = getPreviewUrl(file)

const { stopExecution } = useThread()

<button onClick={stopExecution}>Stop</button>

const { deleteMessage, messages } = useThread()

async function handleDelete(messageId: string) {
  try {
    await deleteMessage(messageId)
  } catch (err) {
    console.error('Failed to delete:', err)
  }
}

// Usage
{messages.map(msg => (
  <div key={msg.id}>
    <span>{msg.content}</span>
    <button onClick={() => handleDelete(msg.id)}>Delete</button>
  </div>
))}

deleteMessage(messageId: string): Promise<void>

const { onEvent } = useThread()

useEffect(() => {
  const unsubscribe = onEvent<{ status: string }>('progress', (data) => {
    console.log('Progress:', data.status)
  })
  return unsubscribe
}, [])

const { onEvent } = useThread()

useEffect(() => {
  const unsubscribe = onEvent<{ path: string; file: { name: string; mimeType: string; size: number } }>('file_created', (data) => {
    console.log('File created:', data.path)
    // Custom notification, analytics, etc.
  })
  return unsubscribe
}, [onEvent])

type ConnectionStatus = 'connecting' | 'connected' | 'disconnected' | 'reconnecting'

import { useThreadId } from "@standardagents/react"

function ThreadInfo() {
  const threadId = useThreadId()
  return <span>Thread: {threadId}</span>
}

import { useState, useEffect, useCallback } from "react"
import { useThread } from "@standardagents/react"

function GamePreview() {
  const { onEvent } = useThread()
  const [gameStatus, setGameStatus] = useState<{ success: boolean } | null>(null)

  useEffect(() => {
    // Subscribe to custom events - returns unsubscribe function
    const unsubscribe = onEvent<{ success: boolean }>('game_built', (data) => {
      setGameStatus(data)
    })
    return unsubscribe
  }, [onEvent])

  return gameStatus?.success ? <GameIframe /> : <LoadingSpinner />
}

// In a tool or hook on the backend
import { emitThreadEvent } from "@standardagents/builder"

emitThreadEvent(flow, "game_built", { success: true })

interface WorkMessage {
  id: string
  type: "workblock"
  content: string | null
  reasoning_content?: string | null
  workItems: WorkItem[]
  status: "pending" | "completed" | "failed"
  created_at: number
  depth?: number
}

interface WorkItem {
  id: string
  type: "tool_call" | "tool_result"
  name?: string
  content: string | null
  status?: "pending" | "success" | "error" | null
  tool_call_id?: string
}

function MessageList() {
  const { workblocks } = useThread()

  return (
    <>
      {workblocks.map((msg) => {
        if ("type" in msg && msg.type === "workblock") {
          return <WorkBlockDisplay key={msg.id} workblock={msg} />
        }
        return <MessageBubble key={msg.id} message={msg} />
      })}
    </>
  )
}

function WorkBlockDisplay({ workblock }: { workblock: WorkMessage }) {
  return (
    <div className={`workblock ${workblock.status}`}>
      {workblock.workItems.map((item) => (
        <div key={item.id}>
          {item.type === "tool_call" ? `Calling ${item.name}...` : item.content}
        </div>
      ))}
    </div>
  )
}

import type {
  // Core types
  Message,
  WorkMessage,
  WorkItem,
  ThreadMessage,
  Thread,

  // Configuration
  AgentBuilderConfig,
  UseThreadOptions,
  GetMessagesOptions,
  SendMessagePayload,
  ThreadProviderOptions,

  // Attachment types
  PendingAttachment,
  AttachmentPayload,
  AttachmentRef,
  ThreadFile,

  // WebSocket events
  MessageDataEvent,
  MessageChunkEvent,
  ErrorEvent,
  ThreadEvent,
  MessageStreamEvent,
  LogDataEvent,
  CustomEvent,
  StoppedByUserEvent,
  LogStreamEvent,

  // WebSocket callbacks
  MessageWebSocketCallbacks,
  LogWebSocketCallbacks,
} from "@standardagents/react"

// Connection status type
import type { ConnectionStatus } from "@standardagents/react"

interface Message {
  id: string
  role: "system" | "user" | "assistant" | "tool"
  content: string | null
  name?: string | null
  tool_calls?: string | null          // JSON array
  tool_call_id?: string | null
  log_id?: string | null
  created_at: number                  // microseconds
  request_sent_at?: number | null
  response_completed_at?: number | null
  status?: "pending" | "completed" | "failed"
  silent?: boolean
  tool_status?: "success" | "error" | null
  reasoning_content?: string | null
  reasoning_details?: string | null   // JSON array
  parent_id?: string | null
  depth?: number
  attachments?: string | null         // JSON array of AttachmentRef
}