@astralform/js 0.1.3 → 0.2.1

package/dist/index.d.ts

@@ -1,9 +1,116 @@
+/**
+ * BlockBuilder — pure rendering engine. Zero default behavior.
+ *
+ * Clients register handlers that map events to blocks.
+ * Both live streaming and restore go through the same engine.
+ *
+ *   import { BlockBuilder, standardHandlers } from "@astralform/js";
+ *   const builder = new BlockBuilder();
+ *   builder.registerHandlers(standardHandlers);
+ */
+
+interface UserBlock {
+    type: "user";
+    id: string;
+    content: string;
+}
+interface TextBlock {
+    type: "text";
+    id: string;
+    content: string;
+    isStreaming: boolean;
+}
+interface ThinkingBlock {
+    type: "thinking";
+    id: string;
+    content: string;
+    isActive: boolean;
+    durationMs?: number;
+}
+interface AgentBlock {
+    type: "agent";
+    id: string;
+    agentName: string;
+    displayName?: string;
+    avatarUrl?: string;
+}
+interface SubagentBlock {
+    type: "subagent";
+    id: string;
+    agentName: string;
+    displayName: string;
+    toolCallId: string;
+    avatarUrl?: string;
+    description?: string;
+    content: string;
+    isActive: boolean;
+}
+interface ToolBlock {
+    type: "tool";
+    id: string;
+    callId: string;
+    toolName: string;
+    displayName?: string;
+    description?: string;
+    arguments?: Record<string, unknown>;
+    status: string;
+    iconUrl?: string;
+    toolCategory?: string;
+    sources?: {
+        title: string;
+        url: string;
+        snippet?: string;
+    }[];
+    durationMs?: number;
+    result?: string;
+}
+interface ErrorBlock {
+    type: "error";
+    id: string;
+    message: string;
+}
+type Block = UserBlock | TextBlock | ThinkingBlock | AgentBlock | SubagentBlock | ToolBlock | ErrorBlock;
+type EventHandler = (event: ChatEvent, builder: BlockBuilder) => void;
+declare class BlockBuilder {
+    private _blocks;
+    private _handlers;
+    private _onChange;
+    activeTextId: string | null;
+    activeThinkingId: string | null;
+    thinkingStartMs: number | null;
+    on(eventType: string, handler: EventHandler | null): void;
+    registerHandlers(handlers: Record<string, EventHandler | null>): void;
+    processEvent(event: ChatEvent): void;
+    getBlocks(): Block[];
+    reset(): void;
+    setOnChange(fn: (() => void) | null): void;
+    addBlock(block: Block): void;
+    updateBlock<T extends Block["type"]>(id: string, updater: (block: Extract<Block, {
+        type: T;
+    }>) => Extract<Block, {
+        type: T;
+    }>): void;
+    /** Update any block by id with a partial update (type-loose for handlers). */
+    patchBlock(id: string, patch: Partial<Block>): void;
+    findBlock(predicate: (b: Block) => boolean): Block | undefined;
+    nextId(): string;
+    private _notify;
+}
+
 interface AstralformConfig {
     apiKey: string;
     baseURL?: string;
     userId: string;
     fetch?: typeof globalThis.fetch;
 }
+interface UserMessageEvent {
+    type: "user_message";
+    content: string;
+}
+interface TitleGeneratedEvent {
+    type: "title_generated";
+    title: string;
+}
 interface MessageStartEvent {
     type: "message_start";
     message_id: string;
@@ -37,6 +144,12 @@ interface ToolUseEndEvent {
     call_id: string;
     tool: string;
     result?: string;
+    sources?: {
+        title: string;
+        url: string;
+        snippet?: string;
+    }[];
+    duration_ms?: number;
 }
 interface AgentStartEvent {
     type: "agent_start";
@@ -117,6 +230,8 @@ interface MessageStopEvent {
     type: "message_stop";
     stop_reason: "end_turn" | "tool_use";
     title?: string;
+    metrics?: Record<string, unknown>;
+    job_id?: string;
 }
 interface SSEErrorEvent {
     type: "error";
@@ -138,21 +253,28 @@ interface AssetCreatedEvent {
     media_type: string;
     size_bytes: number;
 }
-interface ActivitySSEEvent {
-    type: "activity";
-    activity_id: string;
+interface TimelineEntrySSEEvent {
+    type: "timeline_entry";
+    id: string;
     status: "started" | "completed";
-    category: string;
-    title: string;
+    kind?: string;
+    agent_name?: string;
+    tool_name?: string;
+    display_name?: string;
+    tool_category?: string;
+    viewer?: string;
+    call_id?: string;
     detail?: string;
+    started_at?: number;
+    duration_ms?: number;
+    output_summary?: string;
     sources?: Array<{
         title: string;
         url: string;
         snippet?: string;
     }>;
-    tool_name?: string;
-    agent_name?: string;
-    duration_ms?: number;
+    parent_id?: string;
+    structured_output?: Record<string, unknown>;
 }
 interface EditorContentStartEvent {
     type: "editor_content_start";
@@ -176,9 +298,15 @@ interface RetryEvent {
     max_attempts: number;
     delay_seconds: number;
 }
-type SSEEvent = MessageStartEvent | ContentBlockDeltaEvent | ToolUseStartEvent | ToolUseEndEvent | AgentStartEvent | AgentEndEvent | SubagentStartEvent | SubagentContentDeltaEvent | SubagentUpdateEvent | SubagentEndEvent | SubagentToolUseEvent | ThinkingDeltaEvent | ThinkingCompleteEvent | SourcesEvent | CapsuleOutputEvent | CapsuleOutputChunkEvent | TodoUpdateEvent | MessageStopEvent | AssetCreatedEvent | ActivitySSEEvent | EditorContentStartEvent | EditorContentDeltaEvent | EditorContentEndEvent | RetryEvent | SSEErrorEvent;
+type SSEEvent = MessageStartEvent | UserMessageEvent | TitleGeneratedEvent | ContentBlockDeltaEvent | ToolUseStartEvent | ToolUseEndEvent | AgentStartEvent | AgentEndEvent | SubagentStartEvent | SubagentContentDeltaEvent | SubagentUpdateEvent | SubagentEndEvent | SubagentToolUseEvent | ThinkingDeltaEvent | ThinkingCompleteEvent | SourcesEvent | CapsuleOutputEvent | CapsuleOutputChunkEvent | TodoUpdateEvent | MessageStopEvent | AssetCreatedEvent | TimelineEntrySSEEvent | EditorContentStartEvent | EditorContentDeltaEvent | EditorContentEndEvent | RetryEvent | SSEErrorEvent;
 type ChatEvent = {
     type: "connected";
+} | {
+    type: "user_message";
+    content: string;
+} | {
+    type: "title_generated";
+    title: string;
 } | {
     type: "chunk";
     text: string;
@@ -197,6 +325,12 @@ type ChatEvent = {
     callId: string;
     toolName: string;
     result?: string;
+    sources?: {
+        title: string;
+        url: string;
+        snippet?: string;
+    }[];
+    durationMs?: number;
 } | {
     type: "agent_start";
     agentName: string;
@@ -260,6 +394,8 @@ type ChatEvent = {
     conversationId: string;
     messageId: string;
     title?: string;
+    metrics?: Record<string, unknown>;
+    job_id?: string;
 } | {
     type: "subagent_tool_use";
     agentName: string;
@@ -279,20 +415,27 @@ type ChatEvent = {
     maxAttempts: number;
     delaySeconds: number;
 } | {
-    type: "activity";
-    activityId: string;
+    type: "timeline_entry";
+    id: string;
     status: "started" | "completed";
-    category: string;
-    title: string;
+    kind?: string;
+    agent_name?: string;
+    tool_name?: string;
+    display_name?: string;
+    tool_category?: string;
+    viewer?: string;
+    call_id?: string;
     detail?: string;
+    started_at?: number;
+    duration_ms?: number;
+    output_summary?: string;
     sources?: Array<{
         title: string;
         url: string;
         snippet?: string;
     }>;
-    toolName?: string;
-    agentName?: string;
-    durationMs?: number;
+    parent_id?: string;
+    structured_output?: Record<string, unknown>;
 } | {
     type: "editor_content_start";
     callId: string;
@@ -309,6 +452,9 @@ type ChatEvent = {
 } | {
     type: "model_info";
     name: string;
+} | {
+    type: "blocks_changed";
+    blocks: Block[];
 } | {
     type: "error";
     error: Error;
@@ -487,7 +633,7 @@ declare class AstralformClient {
     deleteConversation(id: string): Promise<void>;
     getAgents(): Promise<AgentInfo[]>;
     getSkills(): Promise<SkillInfo[]>;
-    getConversationEvents(conversationId: string): Promise<ConversationEvent[]>;
+    getConversationEvents(conversationId: string, jobId?: string): Promise<ConversationEvent[]>;
     submitToolResult(request: ToolResultRequest): Promise<void>;
     private mapAsset;
     uploadFile(conversationId: string, file: Blob, filename?: string): Promise<ConversationAsset>;
@@ -540,6 +686,7 @@ declare class ChatSession {
     readonly client: AstralformClient;
     readonly toolRegistry: ToolRegistry;
     readonly storage: ChatStorage;
+    readonly blockBuilder: BlockBuilder;
     conversationId: string | null;
     conversations: Conversation[];
     messages: Message[];
@@ -560,12 +707,14 @@ declare class ChatSession {
     activeTools: Map<string, ToolState>;
     private handlers;
     private abortController;
-    constructor(config: AstralformConfig, storage?: ChatStorage);
+    constructor(config: AstralformConfig, storage?: ChatStorage, blockBuilder?: BlockBuilder);
     on(handler: ChatEventHandler): () => void;
     private emit;
     connect(): Promise<void>;
     send(content: string, options?: SendOptions): Promise<void>;
-    resendFromCheckpoint(messageId: string, newContent: string): Promise<void>;
+    resendFromCheckpoint(messageId: string, newContent: string, options?: {
+        enableSearch?: boolean;
+    }): Promise<void>;
     private resetStreamingState;
     private processStream;
     /** Last received sequence number for resumable reconnection */
@@ -573,6 +722,10 @@ declare class ChatSession {
     /** Current job ID for cancellation */
     private currentJobId;
     private consumeJobStream;
+    /**
+     * Shared event consumption loop used by both consumeJobStream and reconnectToJob.
+     */
+    private consumeEventStream;
     /**
      * Apply a single SSE event to session state and notify consumers.
      * Shared between live streaming and historical event replay.
@@ -580,18 +733,37 @@ declare class ChatSession {
     private applyEvent;
     private executeClientTools;
     private completeStream;
-    disconnect(): void;
-    createNewConversation(): Promise<string>;
-    switchConversation(id: string): Promise<void>;
     /**
-     * Replay a single persisted event to reconstruct session state.
-     * Skips text deltas (final content is already in messages[]).
+     * Load conversation context (messages) without replaying events.
+     * Used before reconnectToJob — SSE replay handles event replay.
+     */
+    loadConversation(id: string): Promise<void>;
+    /**
+     * Reconnect to a running job's SSE stream (e.g. after page reload).
+     * Replays all events from the beginning and continues live.
+     * Does NOT reset BlockBuilder — caller controls reset.
      */
-    private replayEvent;
+    reconnectToJob(jobId: string): Promise<void>;
+    disconnect(): void;
+    createNewConversation(): Promise<string>;
+    switchConversation(id: string, jobId?: string): Promise<void>;
     deleteConversation(id: string): Promise<void>;
     toggleClientTool(name: string): boolean;
 }
 
+/**
+ * Standard event handlers for BlockBuilder.
+ *
+ * These define the default event→block mapping rules. Clients import
+ * and register them explicitly:
+ *
+ *   import { BlockBuilder, standardHandlers } from "@astralform/js";
+ *   const builder = new BlockBuilder();
+ *   builder.registerHandlers(standardHandlers);
+ */
+
+declare const standardHandlers: Record<string, EventHandler>;
+
 declare class AstralformError extends Error {
     code: string;
     constructor(message: string, code: string);
@@ -622,4 +794,4 @@ declare function generateId(): string;
  */
 declare function streamJobSSE(options: StreamJobSSEOptions): AsyncGenerator<ChatStreamEvent>;
 
-export { type AgentEndEvent, type AgentInfo, type AgentStartEvent, AstralformClient, type AstralformConfig, AstralformError, AuthenticationError, type CapsuleOutput, type CapsuleOutputChunkEvent, type CapsuleOutputEvent, type ChatEvent, ChatSession, type ChatStorage, type ChatStreamEvent, type ChatStreamRequest, ConnectionError, type ContentBlockDeltaEvent, type Conversation, type ConversationAsset, type ConversationEvent, InMemoryStorage, type JobCreateResponse, LLMNotConfiguredError, type Message, type MessageStartEvent, type MessageStopEvent, type ProjectStatus, RateLimitError, type RetryEvent, type SSEErrorEvent, type SSEEvent, type SendOptions, ServerError, type SkillInfo, type Source, type SourcesEvent, StreamAbortedError, type StreamJobSSEOptions, type SubagentContentDeltaEvent, type SubagentEndEvent, type SubagentStartEvent, type SubagentState, type SubagentToolUseEvent, type ThinkingCompleteEvent, type ThinkingDeltaEvent, type TodoItem, type TodoUpdateEvent, type ToolCallRequest, type ToolDefinition, type ToolHandler, ToolRegistry, type ToolResult, type ToolResultRequest, type ToolState, type ToolUseEndEvent, type ToolUseStartEvent, generateId, streamJobSSE };
+export { type AgentBlock, type AgentEndEvent, type AgentInfo, type AgentStartEvent, AstralformClient, type AstralformConfig, AstralformError, AuthenticationError, type Block, BlockBuilder, type CapsuleOutput, type CapsuleOutputChunkEvent, type CapsuleOutputEvent, type ChatEvent, ChatSession, type ChatStorage, type ChatStreamEvent, type ChatStreamRequest, ConnectionError, type ContentBlockDeltaEvent, type Conversation, type ConversationAsset, type ConversationEvent, type ErrorBlock, type EventHandler, InMemoryStorage, type JobCreateResponse, LLMNotConfiguredError, type Message, type MessageStartEvent, type MessageStopEvent, type ProjectStatus, RateLimitError, type RetryEvent, type SSEErrorEvent, type SSEEvent, type SendOptions, ServerError, type SkillInfo, type Source, type SourcesEvent, StreamAbortedError, type StreamJobSSEOptions, type SubagentBlock, type SubagentContentDeltaEvent, type SubagentEndEvent, type SubagentStartEvent, type SubagentState, type SubagentToolUseEvent, type TextBlock, type ThinkingBlock, type ThinkingCompleteEvent, type ThinkingDeltaEvent, type TodoItem, type TodoUpdateEvent, type ToolBlock, type ToolCallRequest, type ToolDefinition, type ToolHandler, ToolRegistry, type ToolResult, type ToolResultRequest, type ToolState, type ToolUseEndEvent, type ToolUseStartEvent, type UserBlock, generateId, standardHandlers, streamJobSSE };