API Reference
All exports and types for @neeter/server, @neeter/core, @neeter/react, and @neeter/types
For usage examples, see the Server Guide and Client Guide.
@neeter/server
| Export | Description |
|---|---|
SessionManager<TCtx> | Manages agent sessions — create, resume, list history, optional persistence |
SessionManagerOptions | Constructor options — idleTimeoutMs, store |
Session<TCtx> | A single session — id, sdkSessionId, context, pushMessage(), permissionGate, abort() |
SessionInit<TCtx> | Factory return type — model, systemPrompt, permissionMode, mcpServers, extraArgs, env, etc. |
ResumeOptions | Options for SessionManager.resume() — sdkSessionId, forkSession, resumeSessionAt |
sessionMeta(session) | Extract a SessionHistoryEntry from a Session |
extractText(content) | Pull the text portion from a UserMessageContent value |
createJsonSessionStore(dataDir) | File-based SessionStore using append-only JSONL + JSON metadata |
MessageTranslator<TCtx> | Converts SDK messages to SSE events |
TranslatorConfig<TCtx> | Translator options — onToolResult hook |
createAgentRouter<TCtx>(config) | Returns a Hono app with session, SSE, resume, and permission routes |
PermissionGate | Per-session deferred-promise map for tool approval and user questions |
PushChannel<T> | Async iterable queue for feeding messages to the SDK |
sseEncode(event) | Formats an SSEEvent as an SSE string |
createSandboxHook(dir, resolve) | PreToolUse hook that blocks file operations outside a sandbox directory |
streamSession(session, translator, onEvent?) | Async generator yielding SSEEvents, with optional persistence callback |
@neeter/core
Framework-agnostic state management, agent lifecycle, and utilities. Use standalone for vanilla JS apps or as the foundation for @neeter/react.
| Export | Description |
|---|---|
AgentClient | Framework-agnostic client managing EventSource lifecycle, session creation, resumption, and message sending |
AgentClientConfig | Constructor options — endpoint, onCustomEvent |
ResumeOptions | Options for resuming a session — sdkSessionId, fork, resumeSessionAt |
RewindOptions | Options for rewinding file checkpoints — dryRun |
createChatStore() | Creates a vanilla Zustand store |
replayEvents(store, events, options?) | Reconstruct chat store state from persisted SSEEvent[]. Pass stopAtCheckpoint to truncate at a checkpoint |
registerWidget(registration) | Register a component for a tool name |
getWidget(toolName) | Look up a registered widget |
stripMcpPrefix(name) | "mcp__server__tool" → "tool" |
findMatchingApproval(request, toolCall) | Find approval request matching a tool call |
isApprovalClaimedByToolCall(request, messages) | Check if approval is claimed by any non-terminal tool call in a ChatMessage[] |
cn(...inputs) | clsx + tailwind-merge utility for class merging |
@neeter/react
React-specific hooks, components, and widgets. Re-exports all @neeter/core utilities for convenience.
| Export | Description |
|---|---|
AgentProvider | Context provider — wraps store + SSE connection. Props: endpoint, resumeSessionId, onCustomEvent |
useAgentContext() | Returns { sessionId, sdkSessionId, sessionHistory, sendMessage, stopSession, respondToPermission, resumeSession, rewindSession, newSession, refreshHistory, store } |
useChatStore(selector) | Zustand selector hook into chat state |
useAgent(store, config?) | SSE connection hook (used internally by AgentProvider). Config: endpoint, resumeSessionId, onCustomEvent |
MessageList | Auto-scrolling message list with pending permissions and thinking indicator |
TextMessage | Markdown-rendered message bubble |
ChatInput | Textarea + send/stop button (accepts onStop, isStreaming) |
ToolCallCard | Lifecycle-aware tool call display with inline approval |
PendingPermissions | Renders pending tool approval and user question cards |
RollbackButton | Button that triggers file checkpoint rollback for a given message |
ToolApprovalCard | Tool approval card with Allow/Deny buttons |
UserQuestionCard | Structured question card with option selection |
ThinkingBlock | Collapsible card displaying extended thinking text |
ThinkingIndicator | Animated dots shown while agent is generating |
CollapsibleCard | Expandable card wrapper |
StatusDot | Phase-colored status indicator |
cn(...inputs) | clsx + tailwind-merge utility for class merging |
registerWidget(registration) | Register a component for a tool name |
getWidget(toolName) | Look up a registered widget |
stripMcpPrefix(name) | "mcp__server__tool" → "tool" |
Types
Re-exported from @neeter/server, @neeter/core, and @neeter/react:
| Type | Description |
|---|---|
SSEEvent | { event: string, data: string } |
ChatMessage | { id, role, content, thinking?, toolCalls? } |
ToolCallInfo | { id, name, input, partialInput?, result?, error?, status } |
ToolCallPhase | "pending" | "streaming_input" | "running" | "complete" | "error" |
WidgetProps<TResult> | Props passed to widget components |
WidgetRegistration<TResult> | Widget registration — toolName, label, richLabel?, inputRenderer?, component |
ChatStore | StoreApi<ChatStoreShape> — vanilla Zustand store |
ChatStoreShape | Full state + actions interface (includes totalCost, totalTurns, totalInputTokens, totalOutputTokens, modelUsage, lastStopReason) |
TextBlock | { type: "text", text: string } — text content block |
Base64ImageSource | { type: "base64", media_type, data } — base64-encoded image source |
ImageBlock | { type: "image", source: Base64ImageSource } — image content block |
ContentBlock | TextBlock | ImageBlock — single content block |
UserMessageContent | string | ContentBlock[] — content for a user message |
CustomEvent<T> | { name: string, value: T } — structured app-level event |
SessionInitEvent | { sdkSessionId, model, tools } — session initialization payload |
SessionHistoryEntry | { sdkSessionId, description, createdAt, lastActivityAt } — session metadata |
SessionRecord | { meta: SessionHistoryEntry, events: SSEEvent[] } — persistable session data |
SessionStore | Pluggable persistence backend — save, load, list, delete |
PermissionRequest | ToolApprovalRequest | UserQuestionRequest — pending permission |
PermissionResponse | ToolApprovalResponse | UserQuestionResponse — user's answer |
ToolApprovalRequest | { kind, requestId, toolName, toolUseId?, input, description? } |
ToolApprovalResponse | { kind, requestId, behavior: "allow" | "deny", message? } |
UserQuestion | { question, header?, options?, multiSelect? } |
UserQuestionOption | { label, description, markdown? } — single option in a UserQuestion |
UserQuestionRequest | { kind, requestId, questions: UserQuestion[] } |
UserQuestionResponse | { kind, requestId, answers: Record<string, string> } |
TokenUsage | { inputTokens, outputTokens, cacheCreationInputTokens, cacheReadInputTokens } |
ModelUsage | TokenUsage + { webSearchRequests, costUSD, contextWindow } — per-model breakdown |
StopReason | "end_turn" | "max_tokens" | "stop_sequence" | "refusal" | "tool_use" | null |
TurnCompleteData | { numTurns, cost, stopReason: StopReason, usage: TokenUsage | null, modelUsage: Record<string, ModelUsage> | null } |