@astralform/js 0.2.1 → 0.2.3

package/dist/index.d.cts

@@ -13,6 +13,7 @@ interface UserBlock {
     type: "user";
     id: string;
     content: string;
+    createdAt?: number;
 }
 interface TextBlock {
     type: "text";
@@ -64,13 +65,66 @@ interface ToolBlock {
     durationMs?: number;
     result?: string;
 }
+interface CapsuleBlock {
+    type: "capsule";
+    id: string;
+    callId: string;
+    toolName: string;
+    command?: string;
+    output: string;
+    durationMs?: number;
+    isActive: boolean;
+}
+interface AssetBlock {
+    type: "asset";
+    id: string;
+    assetId: string;
+    name: string;
+    url: string;
+    mediaType: string;
+    sizeBytes: number;
+}
+interface TodoBlock {
+    type: "todo";
+    id: string;
+    todos: {
+        content: string;
+        status: string;
+    }[];
+}
+interface EditorBlock {
+    type: "editor";
+    id: string;
+    callId: string;
+    path: string;
+    language: string;
+    content: string;
+    isStreaming: boolean;
+}
 interface ErrorBlock {
     type: "error";
     id: string;
     message: string;
 }
-type Block = UserBlock | TextBlock | ThinkingBlock | AgentBlock | SubagentBlock | ToolBlock | ErrorBlock;
-type EventHandler = (event: ChatEvent, builder: BlockBuilder) => void;
+interface DesktopStreamBlock {
+    type: "desktop_stream";
+    id: string;
+    url: string;
+    authKey: string;
+    sandboxId: string;
+}
+interface AttachmentBlock {
+    type: "attachment";
+    id: string;
+    files: {
+        name: string;
+        path: string;
+        mediaType: string;
+        sizeBytes: number;
+    }[];
+}
+type Block = UserBlock | TextBlock | ThinkingBlock | AgentBlock | SubagentBlock | ToolBlock | CapsuleBlock | AssetBlock | TodoBlock | EditorBlock | DesktopStreamBlock | AttachmentBlock | ErrorBlock;
+type EventHandler$1 = (event: ChatEvent, builder: BlockBuilder) => void;
 declare class BlockBuilder {
     private _blocks;
     private _handlers;
@@ -78,8 +132,10 @@ declare class BlockBuilder {
     activeTextId: string | null;
     activeThinkingId: string | null;
     thinkingStartMs: number | null;
-    on(eventType: string, handler: EventHandler | null): void;
-    registerHandlers(handlers: Record<string, EventHandler | null>): void;
+    activeEditorId: string | null;
+    activeTodoId: string | null;
+    on(eventType: string, handler: EventHandler$1 | null): void;
+    registerHandlers(handlers: Record<string, EventHandler$1 | null>): void;
     processEvent(event: ChatEvent): void;
     getBlocks(): Block[];
     reset(): void;
@@ -103,9 +159,47 @@ interface AstralformConfig {
     userId: string;
     fetch?: typeof globalThis.fetch;
 }
+declare const ChatEventType: {
+    readonly Connected: "connected";
+    readonly BlocksChanged: "blocks_changed";
+    readonly UserMessage: "user_message";
+    readonly TitleGenerated: "title_generated";
+    readonly ModelInfo: "model_info";
+    readonly Chunk: "chunk";
+    readonly ToolCall: "tool_call";
+    readonly ToolExecuting: "tool_executing";
+    readonly ToolProgress: "tool_progress";
+    readonly ToolCompleted: "tool_completed";
+    readonly ToolEnd: "tool_end";
+    readonly AgentStart: "agent_start";
+    readonly AgentEnd: "agent_end";
+    readonly ThinkingDelta: "thinking_delta";
+    readonly ThinkingComplete: "thinking_complete";
+    readonly SubagentStart: "subagent_start";
+    readonly SubagentChunk: "subagent_chunk";
+    readonly SubagentUpdate: "subagent_update";
+    readonly SubagentEnd: "subagent_end";
+    readonly SubagentToolUse: "subagent_tool_use";
+    readonly CapsuleOutput: "capsule_output";
+    readonly CapsuleOutputChunk: "capsule_output_chunk";
+    readonly AssetCreated: "asset_created";
+    readonly TodoUpdate: "todo_update";
+    readonly EditorContentStart: "editor_content_start";
+    readonly EditorContentDelta: "editor_content_delta";
+    readonly EditorContentEnd: "editor_content_end";
+    readonly Complete: "complete";
+    readonly Error: "error";
+    readonly Disconnected: "disconnected";
+    readonly Retry: "retry";
+    readonly ContextUpdate: "context_update";
+    readonly DesktopStream: "desktop_stream";
+    readonly AttachmentStaged: "attachment_staged";
+    readonly WorkspaceReady: "workspace_ready";
+};
 interface UserMessageEvent {
     type: "user_message";
     content: string;
+    created_at?: number;
 }
 interface TitleGeneratedEvent {
     type: "title_generated";
@@ -151,6 +245,23 @@ interface ToolUseEndEvent {
     }[];
     duration_ms?: number;
 }
+interface ToolExecutingEvent {
+    type: "tool_executing";
+    call_id: string;
+    tool: string;
+}
+interface ToolProgressEvent {
+    type: "tool_progress";
+    call_id: string;
+    tool: string;
+    index: number;
+    total: number;
+    item: {
+        title: string;
+        url: string;
+        snippet?: string;
+    };
+}
 interface AgentStartEvent {
     type: "agent_start";
     agent_name: string;
@@ -200,13 +311,6 @@ interface ThinkingDeltaEvent {
 interface ThinkingCompleteEvent {
     type: "thinking_complete";
 }
-interface SourcesEvent {
-    type: "sources";
-    sources: Array<{
-        title: string;
-        url: string;
-    }>;
-}
 interface CapsuleOutputEvent {
     type: "capsule_output";
     tool_name: string;
@@ -253,29 +357,6 @@ interface AssetCreatedEvent {
     media_type: string;
     size_bytes: number;
 }
-interface TimelineEntrySSEEvent {
-    type: "timeline_entry";
-    id: string;
-    status: "started" | "completed";
-    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;
-    }>;
-    parent_id?: string;
-    structured_output?: Record<string, unknown>;
-}
 interface EditorContentStartEvent {
     type: "editor_content_start";
     call_id: string;
@@ -298,12 +379,39 @@ interface RetryEvent {
     max_attempts: number;
     delay_seconds: number;
 }
-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;
+interface ContextUpdateEvent {
+    type: "context_update";
+    context: Record<string, unknown>;
+    phase?: string;
+    updated_at?: number;
+}
+interface DesktopStreamEvent {
+    type: "desktop_stream";
+    url: string;
+    auth_key: string;
+    sandbox_id: string;
+}
+interface AttachmentStagedEvent {
+    type: "attachment_staged";
+    files: {
+        name: string;
+        path: string;
+        media_type: string;
+        size_bytes: number;
+    }[];
+}
+interface WorkspaceReadyEvent {
+    type: "workspace_ready";
+    conversation_id: string;
+    sandbox_id: string;
+}
+type SSEEvent = MessageStartEvent | UserMessageEvent | TitleGeneratedEvent | ContentBlockDeltaEvent | ToolUseStartEvent | ToolUseEndEvent | ToolExecutingEvent | ToolProgressEvent | AgentStartEvent | AgentEndEvent | SubagentStartEvent | SubagentContentDeltaEvent | SubagentUpdateEvent | SubagentEndEvent | SubagentToolUseEvent | ThinkingDeltaEvent | ThinkingCompleteEvent | CapsuleOutputEvent | CapsuleOutputChunkEvent | TodoUpdateEvent | MessageStopEvent | AssetCreatedEvent | EditorContentStartEvent | EditorContentDeltaEvent | EditorContentEndEvent | RetryEvent | ContextUpdateEvent | DesktopStreamEvent | AttachmentStagedEvent | WorkspaceReadyEvent | SSEErrorEvent;
 type ChatEvent = {
     type: "connected";
 } | {
     type: "user_message";
     content: string;
+    createdAt?: number;
 } | {
     type: "title_generated";
     title: string;
@@ -316,10 +424,22 @@ type ChatEvent = {
 } | {
     type: "tool_executing";
     name: string;
+    call_id?: string;
 } | {
     type: "tool_completed";
     name: string;
     result: string;
+} | {
+    type: "tool_progress";
+    callId: string;
+    tool: string;
+    index: number;
+    total: number;
+    item: {
+        title: string;
+        url: string;
+        snippet?: string;
+    };
 } | {
     type: "tool_end";
     callId: string;
@@ -366,12 +486,6 @@ type ChatEvent = {
     agentName: string;
     displayName: string;
     toolCallId: string;
-} | {
-    type: "sources";
-    sources: Array<{
-        title: string;
-        url: string;
-    }>;
 } | {
     type: "capsule_output";
     toolName: string;
@@ -415,27 +529,10 @@ type ChatEvent = {
     maxAttempts: number;
     delaySeconds: number;
 } | {
-    type: "timeline_entry";
-    id: string;
-    status: "started" | "completed";
-    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;
-    }>;
-    parent_id?: string;
-    structured_output?: Record<string, unknown>;
+    type: "context_update";
+    context: Record<string, unknown>;
+    phase?: string;
+    updatedAt?: number;
 } | {
     type: "editor_content_start";
     callId: string;
@@ -449,6 +546,23 @@ type ChatEvent = {
 } | {
     type: "editor_content_end";
     callId: string;
+} | {
+    type: "desktop_stream";
+    url: string;
+    authKey: string;
+    sandboxId: string;
+} | {
+    type: "attachment_staged";
+    files: {
+        name: string;
+        path: string;
+        mediaType: string;
+        sizeBytes: number;
+    }[];
+} | {
+    type: "workspace_ready";
+    conversationId: string;
+    sandboxId: string;
 } | {
     type: "model_info";
     name: string;
@@ -591,7 +705,7 @@ interface ConversationEvent {
     event: string;
     data: Record<string, unknown>;
 }
-interface SendOptions {
+interface SendOptions$1 {
     conversationId?: string;
     enabledClientTools?: string[];
     uploadIds?: string[];
@@ -618,8 +732,8 @@ declare class AstralformClient {
     constructor(config: AstralformConfig);
     private get headers();
     private request;
-    private get;
-    private post;
+    get<T>(path: string): Promise<T>;
+    post<T>(path: string, body: unknown): Promise<T>;
     private del;
     private handleError;
     getHealth(): Promise<{
@@ -701,7 +815,6 @@ declare class ChatSession {
     thinkingContent: string;
     isThinking: boolean;
     activeSubagents: Map<string, SubagentState>;
-    sources: Source[];
     capsuleOutputs: CapsuleOutput[];
     todos: TodoItem[];
     activeTools: Map<string, ToolState>;
@@ -711,7 +824,7 @@ declare class ChatSession {
     on(handler: ChatEventHandler): () => void;
     private emit;
     connect(): Promise<void>;
-    send(content: string, options?: SendOptions): Promise<void>;
+    send(content: string, options?: SendOptions$1): Promise<void>;
     resendFromCheckpoint(messageId: string, newContent: string, options?: {
         enableSearch?: boolean;
     }): Promise<void>;
@@ -720,7 +833,7 @@ declare class ChatSession {
     /** Last received sequence number for resumable reconnection */
     private lastSeq;
     /** Current job ID for cancellation */
-    private currentJobId;
+    currentJobId: string | null;
     private consumeJobStream;
     /**
      * Shared event consumption loop used by both consumeJobStream and reconnectToJob.
@@ -744,6 +857,10 @@ declare class ChatSession {
      * Does NOT reset BlockBuilder — caller controls reset.
      */
     reconnectToJob(jobId: string): Promise<void>;
+    /** Detach from the SSE stream without cancelling the job.
+     *  The backend job keeps running — caller can reconnect later. */
+    detach(): void;
+    /** Stop the job and disconnect (explicit user action). */
     disconnect(): void;
     createNewConversation(): Promise<string>;
     switchConversation(id: string, jobId?: string): Promise<void>;
@@ -762,7 +879,7 @@ declare class ChatSession {
  *   builder.registerHandlers(standardHandlers);
  */
 
-declare const standardHandlers: Record<string, EventHandler>;
+declare const standardHandlers: Record<string, EventHandler$1>;
 
 declare class AstralformError extends Error {
     code: string;
@@ -794,4 +911,77 @@ declare function generateId(): string;
  */
 declare function streamJobSSE(options: StreamJobSSEOptions): AsyncGenerator<ChatStreamEvent>;
 
-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 };
+/**
+ * StreamManager — high-level conversation lifecycle coordinator.
+ *
+ * Sits on top of ChatSession and manages the state machine for
+ * multi-conversation SSE streaming. Framework-agnostic: emits
+ * callbacks instead of writing to any state management library.
+ *
+ *   import { ChatSession, StreamManager } from "@astralform/js";
+ *   const session = new ChatSession({ ... });
+ *   const manager = new StreamManager(session);
+ *   manager.on("blocksChanged", (convId, blocks) => { ... });
+ *   await manager.send("Hello");
+ */
+
+type StreamState = "idle" | "streaming" | "restoring" | "detached";
+interface SendOptions {
+    enableSearch?: boolean;
+    agentName?: string;
+    uploadIds?: string[];
+}
+type StreamManagerEvent = {
+    type: "stateChange";
+    state: StreamState;
+    conversationId: string | null;
+} | {
+    type: "blocksChanged";
+    conversationId: string;
+    blocks: Block[];
+} | {
+    type: "conversationChanged";
+    conversationId: string | null;
+} | {
+    type: "backgroundJobsChanged";
+    jobs: ReadonlyMap<string, string>;
+} | {
+    type: "event";
+    conversationId: string | null;
+    event: ChatEvent;
+} | {
+    type: "versionsReady";
+    conversationId: string;
+    count: number;
+};
+type EventHandler = (event: StreamManagerEvent) => void;
+declare class StreamManager {
+    private session;
+    private _state;
+    private _activeConversationId;
+    private _backgroundJobs;
+    private handlers;
+    private unsub;
+    constructor(session: ChatSession);
+    get state(): StreamState;
+    get activeConversationId(): string | null;
+    get backgroundJobs(): ReadonlyMap<string, string>;
+    on(handler: EventHandler): () => void;
+    private emit;
+    private setState;
+    private attach;
+    private onSessionEvent;
+    send(content: string, options?: SendOptions): Promise<void>;
+    regenerate(): Promise<void>;
+    switchTo(conversationId: string): Promise<void>;
+    createConversation(): Promise<string>;
+    deleteConversation(id: string): Promise<void>;
+    stop(): void;
+    destroy(): void;
+    private prepareUserBlock;
+    private finalizeStream;
+    private restore;
+    private setActiveConversation;
+}
+
+export { type AgentBlock, type AgentEndEvent, type AgentInfo, type AgentStartEvent, type AssetBlock, AstralformClient, type AstralformConfig, AstralformError, type AttachmentBlock, type AttachmentStagedEvent, AuthenticationError, type Block, BlockBuilder, type CapsuleBlock, type CapsuleOutput, type CapsuleOutputChunkEvent, type CapsuleOutputEvent, type ChatEvent, ChatEventType, ChatSession, type ChatStorage, type ChatStreamEvent, type ChatStreamRequest, ConnectionError, type ContentBlockDeltaEvent, type Conversation, type ConversationAsset, type ConversationEvent, type DesktopStreamBlock, type DesktopStreamEvent, type EditorBlock, type ErrorBlock, type EventHandler$1 as 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, StreamAbortedError, type StreamJobSSEOptions, StreamManager, type StreamManagerEvent, type StreamState, type SubagentBlock, type SubagentContentDeltaEvent, type SubagentEndEvent, type SubagentStartEvent, type SubagentState, type SubagentToolUseEvent, type TextBlock, type ThinkingBlock, type ThinkingCompleteEvent, type ThinkingDeltaEvent, type TodoBlock, type TodoItem, type TodoUpdateEvent, type ToolBlock, type ToolCallRequest, type ToolDefinition, type ToolExecutingEvent, type ToolHandler, type ToolProgressEvent, ToolRegistry, type ToolResult, type ToolResultRequest, type ToolState, type ToolUseEndEvent, type ToolUseStartEvent, type UserBlock, type WorkspaceReadyEvent, generateId, standardHandlers, streamJobSSE };