Skip to Content
Baseera Docs

Types

The types @baseera/core exports for messages, tools, events, chat state and context, with their fields.

These are the types you meet most often. All are exported from @baseera/core, and @baseera/react re-exports the ones its hooks use. The wire protocol they describe is version v0.

Messages

interface UserMessage {
  id: string;
  role: "user";
  text: string;
  createdAt: string;
}

interface AssistantMessage {
  id: string;
  role: "assistant";
  text: string;
  toolCalls: ToolCall[];
  sources: Source[];
  createdAt: string;
}

type Message = UserMessage | AssistantMessage;

In the chat controller, the assistant message is a ChatAssistantMessage: the same, but its toolCalls are ChatToolCall[]. ChatMessage is UserMessage | ChatAssistantMessage.

Tools

Prop

Type

That is ToolSpec, what the SDK sends for each tool on every turn. At most 64 tools go in one turn.

ToolDefinition is a ToolSpec plus run(input). RegisteredTool is what the chat controller holds:

Prop

Type

Tool calls

type ToolCallStatus = "pending" | "done" | "rejected" | "failed" | "timed_out";
type ChatToolCallStatus = ToolCallStatus | "awaiting_approval" | "running";

Prop

Type

Sources

See Sources and citations for the fields of Source (ref, title, section, page, url, aliases). SourceLink is { url: string; expiresAt: string }.

Chat state

Prop

Type

PendingApproval is { callId, name, kind: "draft" | "write", input, description }. description is the tool's describe(input), or its name and input as JSON, cut at 300 characters.

Context

interface TurnContext {
  page?: string;
  entity?: { type: string; ref: string; title?: string };
  data?: Record<string, unknown>; // at most 4,096 bytes serialized
}

Requests

TypeFields
StartSessionRequestlocale?
StartSessionResponsesessionId, agent: { name, modes }, createdAt
SessionSnapshotsessionId, agent, messages, pendingTurn: { turnId, callIds, expiresAt } or null
SendTurnRequestmessage: { text }, tools, context?, immersive?
ToolResultsRequestturnId, results, tools, context?, immersive?
ToolResult{ callId, output, approved? }, { callId, rejected: true, reason? } or { callId, error, approved? }

A message is limited to 8,000 characters. The tools are sent again with every tool-results request, because the runtime keeps no tool state between requests.

Stream events

type TurnEvent =
  | { type: "turn.started"; turnId: string; messageId: string }
  | { type: "text.delta"; messageId: string; delta: string }
  | { type: "tool.call"; messageId: string; callId: string; name: string; kind: ToolKind; input: unknown; server?: true }
  | { type: "tool.result"; messageId: string; callId: string; server: true; status: "done" | "failed"; summary?: Record<string, unknown> }
  | { type: "message.sources"; messageId: string; sources: Source[] }
  | { type: "turn.awaiting_tools"; turnId: string; callIds: string[]; expiresAt: string }
  | { type: "turn.done"; turnId: string; finishReason: FinishReason; usage: Usage }
  | { type: "error"; error: ProtocolError }
  // plus immersive.ai_check, immersive.draft and immersive.notice
  ;

type SequencedEvent = TurnEvent & { seq: number };
type FinishReason = "stop" | "cancelled" | "max_steps_reached" | "tool_timeout";
interface Usage { inputTokens: number; outputTokens: number }

TurnEventType, TURN_EVENT_TYPES, TERMINAL_EVENT_TYPES, isTurnEventType and isTerminalEventType are exported too.

Client types

ClientOptions is { publishableKey, getUserToken?, baseUrl? }. BaseeraClientOptions adds fetch?. BaseeraClient is the interface createBaseeraClient returns. RequestOptions is { signal? }.

Theme types

AgentTheme is the theme the owner publishes: color pairs ({ light?, dark? }) for accent, primary, primaryFg, card, cardFg, frame, frameFg, critical, warning, info, success, draft and live, plus radius (such as 12px), font (system, serif, rounded or mono) and logo (an id, never a URL).

Next steps

On this page