@astralform/js 4.2.0 → 4.4.0

package/dist/index.d.cts

@@ -420,6 +420,12 @@ type ChatEvent = {
     type: "user_message";
     content: string;
     createdAt?: number;
+    id?: string;
+    /** This message was steered into a run already in flight — it started
+     *  no turn of its own. Consumers that badge a steer (a "waiting to be
+     *  read" notice) key off this; without it a replayed steer is
+     *  indistinguishable from an ordinary prompt. */
+    steer?: boolean;
 } | {
     type: "title_generated";
     title: string;
@@ -796,7 +802,7 @@ declare class AstralformClient {
     constructor(config: AstralformConfig);
     /**
      * Replace the current OIDC access token without reconstructing the client.
-     * Use after refreshing via the host's token manager (e.g., Supabase JS SDK).
+     * Use after refreshing via the host app's own token manager.
      * Throws if the client was created in API-key mode.
      */
     updateAccessToken(accessToken: string): void;
@@ -980,6 +986,13 @@ declare class ToolRegistry {
 }
 
 type ChatEventHandler = (event: ChatEvent) => void;
+/**
+ * Conversations fetched per page, by ``connect`` and ``loadMoreConversations``
+ * alike. The two must use the same size: the offset is derived from how many
+ * rows the server has returned so far, so a first page of a different size
+ * would leave the second page's offset pointing at the wrong row.
+ */
+declare const CONVERSATION_PAGE_SIZE = 50;
 /**
  * ChatSession — translates the backend wire protocol into typed ChatEvents
  * for consumers. Owns HTTP + SSE plumbing, conversation state, and the
@@ -1000,6 +1013,17 @@ declare class ChatSession {
     readonly protocols: ProtocolRegistry<ProtocolAdapter>;
     conversationId: string | null;
     conversations: Conversation[];
+    /**
+     * Whether another page of conversations may exist on the server.
+     *
+     * Inferred from the last page being full, since the list endpoint returns a
+     * bare array with no total. A total that happens to be an exact multiple of
+     * the page size therefore costs one extra empty request before this flips —
+     * cheaper than adding a count query to every list call.
+     */
+    hasMoreConversations: boolean;
+    /** True while ``loadMoreConversations`` is in flight. */
+    isLoadingConversations: boolean;
     messages: Message[];
     isStreaming: boolean;
     agentStatus: AgentStatus | null;
@@ -1007,6 +1031,32 @@ declare class ChatSession {
     skills: SkillInfo[];
     enabledClientTools: Set<string>;
     modelDisplayName: string | null;
+    /**
+     * Ids of conversations the SERVER has handed us, which is the paging offset.
+     *
+     * Deliberately not ``conversations.length``. That array also holds
+     * conversations created locally and unshifted on top (``createNewConversation``,
+     * and the auto-created conversation in ``consumeJobStream``), so using its
+     * length as the offset would over-count and silently skip a row of real
+     * history on the next page. Tracking ids rather than a counter also makes
+     * deletion self-correcting: removing a server-sourced conversation shifts
+     * every later page up by one, and dropping its id from this set is exactly
+     * that shift — while deleting a purely local one correctly changes nothing.
+     */
+    private serverConversationIds;
+    /**
+     * Bumped every time ``connect()`` re-seeds the conversation list.
+     *
+     * A ``loadMoreConversations`` request issued before a re-seed describes the
+     * OLD paging state, so applying its response afterwards both appends the
+     * wrong rows and corrupts the offset. Concretely: with 100 rows held, an
+     * offset-100 response landing after a reconnect has reset to rows 0-49 would
+     * append rows 100-149 — a 50-row hole — and leave the id set at 100, so every
+     * later page re-requests offset 100 and never advances again. The generation
+     * is captured before the await and rechecked after, so a superseded response
+     * is discarded instead.
+     */
+    private conversationsGeneration;
     private accumulatedText;
     private currentTextPath;
     private handlers;
@@ -1095,7 +1145,7 @@ declare class ChatSession {
      * ``message_start`` in the stream (e.g. ``memory_recall`` from prompt prep),
      * so leading with the prompt keeps the turn in order.
      */
-    replayTurn(id: string, events: ConversationEvent[], userMessageContent?: string): void;
+    replayTurn(id: string, events: ConversationEvent[], userMessageContent?: string, userMessageId?: string, isSteer?: boolean): void;
     /**
      * Load a conversation's messages and replay its persisted history.
      *
@@ -1108,6 +1158,40 @@ declare class ChatSession {
      * job's events.
      */
     switchConversation(id: string, jobId?: string): Promise<void>;
+    /**
+     * Append the next page of conversation history to ``conversations``.
+     *
+     * The list is ordered ``updated_at DESC`` and paged by offset, so a
+     * conversation bumped to the top mid-scroll can surface again in a later
+     * page; ids already held are dropped rather than duplicated. Returns only
+     * the conversations actually appended, which may be empty even on a full
+     * page. Rejects on network failure with ``hasMoreConversations`` still true,
+     * so the caller can retry.
+     *
+     * KNOWN LIMITATION — offset paging is only stable while the prefix already
+     * consumed stays put. The offset tracking here corrects for perturbations
+     * THIS session causes (local unshifts, ``deleteConversation``), but not for
+     * ones it never sees:
+     *
+     * - a conversation this session hasn't loaded yet is bumped to the top (a
+     *   headless routine or another device posting to it), pushing the whole
+     *   list down — it lands inside the consumed prefix, which no later offset
+     *   revisits;
+     * - a conversation is deleted from another tab/device, shrinking the list so
+     *   the next offset lands one row too far in.
+     *
+     * Each perturbation costs at most one conversation off the sidebar, and only
+     * until the next ``connect()`` — that re-seeds page 1 and resets the paging
+     * state, so a reload or reconnect always recovers it. Nothing is lost
+     * server-side. Both cases are pinned by tests in
+     * ``tests/conversation-paging.test.ts``.
+     *
+     * Closing the gap properly needs a stable server cursor (keyset paging on
+     * ``(updated_at, id)``) rather than a raw offset, which is a backend change —
+     * tracking ids client-side cannot discover a row that moved into a region
+     * already scanned.
+     */
+    loadMoreConversations(): Promise<Conversation[]>;
     deleteConversation(id: string): Promise<void>;
     toggleClientTool(name: string): boolean;
 }
@@ -1158,26 +1242,6 @@ declare function generateId(): string;
  */
 declare function streamJobSSE(options: StreamJobSSEOptions): AsyncGenerator<ChatStreamEvent>;
 
-/**
- * StreamManager — high-level conversation lifecycle coordinator.
- *
- * Sits on top of ChatSession and manages the state machine for
- * multi-conversation SSE streaming. Framework-agnostic: emits
- * typed events to registered handlers. Block construction is NOT
- * the SDK's concern — consumers build their own block tree from
- * the forwarded ``ChatEvent`` instances.
- *
- *   import { ChatSession, StreamManager } from "@astralform/js";
- *   const session = new ChatSession({ ... });
- *   const manager = new StreamManager(session);
- *   manager.on((event) => {
- *     if (event.type === "event") {
- *       // event.event is a typed ChatEvent — dispatch to your reducer
- *     }
- *   });
- *   await manager.send("Hello");
- */
-
 type StreamState = "idle" | "streaming" | "restoring" | "detached";
 interface SendOptions extends ModelChoiceOptions {
     agentName?: string;
@@ -1340,4 +1404,4 @@ declare function isEmbeddedResource(value: unknown): value is {
  */
 declare function parseEmbeddedResource(value: unknown): EmbeddedResource | null;
 
-export { type ActiveJob, type AgentIdentity, type AgentInfo, type AgentStatus, type AssetCreatedPayload, type AstralformApiKeyConfig, AstralformClient, type AstralformConfig, AstralformError, type AstralformUserTokenConfig, type AttachmentStagedPayload, AuthenticationError, type BlockDeltaPayload, type ChatEvent, ChatEventType, type ChatEventTypeValue, ChatSession, type ChatStorage, type ChatStreamEvent, type ChatStreamRequest, ConnectionError, type ContextUpdatePayload, type ContextWarningPayload, type Conversation, type ConversationAsset, type ConversationEvent, type DesktopStreamPayload, type EmbeddedResource, type FeedbackRequest, type FeedbackResponse, InMemoryStorage, type JobCreateResponse, type JobStatus, type JobSummary, LLMNotConfiguredError, type MemoryRecallPayload, type MemoryRecord, type MemoryUpdatePayload, type Message, type ModelChoiceOptions, type ModelOption, type MyToolGrantsPage, type PromptSuggestionPayload, type ProtocolAdapter, ProtocolRegistry, RateLimitError, type RateLimitErrorDetails, type RawSseEvent, type ReasoningEffort, type SendOptions, ServerError, type SkillInfo, StreamAbortedError, type StreamJobSSEOptions, StreamManager, type StreamManagerEvent, type StreamState, type SubagentStartPayload, type SubagentStopPayload, type TaskStatus, type TeamAgentSummary, type TeamSummary, type TitleGeneratedPayload, type TodoItem, type TodoUpdatePayload, type ToolApprovalDecision, type ToolApprovalGrantedPayload, type ToolApprovalRequest, type ToolApprovalRequestedPayload, type ToolApprovalScope, type ToolCallRequest, type ToolDefinition, type ToolGrant, type ToolHandler, type ToolHarnessWarningPayload, type ToolPermissionDeniedPayload, ToolRegistry, type ToolResult, type ToolResultRequest, type TurnUsage, type UIComponentsConfig, type UserUnavailablePayload, type WireBlockDelta, type WireBlockDeltaPayload, type WireBlockKind, type WireBlockStart, type WireBlockStatus, type WireBlockStop, type WireCustomEvent, type WireErrorEvent, type WireEvent, type WireInputArgDelta, type WireInputDelta, type WireKeepalive, type WireMessageStart, type WireMessageStop, type WireOutputDelta, type WireRetryEvent, type WireSignatureDelta, type WireStallWarning, type WireStatusDelta, type WireStopReason, type WireTextDelta, type WireThinkingDelta, type WorkspaceReadyPayload, generateId, isEmbeddedResource, mapSseToChat, parseEmbeddedResource, replayEvents, streamJobSSE, translateDelta };
+export { type ActiveJob, type AgentIdentity, type AgentInfo, type AgentStatus, type AssetCreatedPayload, type AstralformApiKeyConfig, AstralformClient, type AstralformConfig, AstralformError, type AstralformUserTokenConfig, type AttachmentStagedPayload, AuthenticationError, type BlockDeltaPayload, CONVERSATION_PAGE_SIZE, type ChatEvent, ChatEventType, type ChatEventTypeValue, ChatSession, type ChatStorage, type ChatStreamEvent, type ChatStreamRequest, ConnectionError, type ContextUpdatePayload, type ContextWarningPayload, type Conversation, type ConversationAsset, type ConversationEvent, type DesktopStreamPayload, type EmbeddedResource, type FeedbackRequest, type FeedbackResponse, InMemoryStorage, type JobCreateResponse, type JobStatus, type JobSummary, LLMNotConfiguredError, type MemoryRecallPayload, type MemoryRecord, type MemoryUpdatePayload, type Message, type ModelChoiceOptions, type ModelOption, type MyToolGrantsPage, type PromptSuggestionPayload, type ProtocolAdapter, ProtocolRegistry, RateLimitError, type RateLimitErrorDetails, type RawSseEvent, type ReasoningEffort, type SendOptions, ServerError, type SkillInfo, StreamAbortedError, type StreamJobSSEOptions, StreamManager, type StreamManagerEvent, type StreamState, type SubagentStartPayload, type SubagentStopPayload, type TaskStatus, type TeamAgentSummary, type TeamSummary, type TitleGeneratedPayload, type TodoItem, type TodoUpdatePayload, type ToolApprovalDecision, type ToolApprovalGrantedPayload, type ToolApprovalRequest, type ToolApprovalRequestedPayload, type ToolApprovalScope, type ToolCallRequest, type ToolDefinition, type ToolGrant, type ToolHandler, type ToolHarnessWarningPayload, type ToolPermissionDeniedPayload, ToolRegistry, type ToolResult, type ToolResultRequest, type TurnUsage, type UIComponentsConfig, type UserUnavailablePayload, type WireBlockDelta, type WireBlockDeltaPayload, type WireBlockKind, type WireBlockStart, type WireBlockStatus, type WireBlockStop, type WireCustomEvent, type WireErrorEvent, type WireEvent, type WireInputArgDelta, type WireInputDelta, type WireKeepalive, type WireMessageStart, type WireMessageStop, type WireOutputDelta, type WireRetryEvent, type WireSignatureDelta, type WireStallWarning, type WireStatusDelta, type WireStopReason, type WireTextDelta, type WireThinkingDelta, type WorkspaceReadyPayload, generateId, isEmbeddedResource, mapSseToChat, parseEmbeddedResource, replayEvents, streamJobSSE, translateDelta };

package/dist/index.d.ts

@@ -420,6 +420,12 @@ type ChatEvent = {
     type: "user_message";
     content: string;
     createdAt?: number;
+    id?: string;
+    /** This message was steered into a run already in flight — it started
+     *  no turn of its own. Consumers that badge a steer (a "waiting to be
+     *  read" notice) key off this; without it a replayed steer is
+     *  indistinguishable from an ordinary prompt. */
+    steer?: boolean;
 } | {
     type: "title_generated";
     title: string;
@@ -796,7 +802,7 @@ declare class AstralformClient {
     constructor(config: AstralformConfig);
     /**
      * Replace the current OIDC access token without reconstructing the client.
-     * Use after refreshing via the host's token manager (e.g., Supabase JS SDK).
+     * Use after refreshing via the host app's own token manager.
      * Throws if the client was created in API-key mode.
      */
     updateAccessToken(accessToken: string): void;
@@ -980,6 +986,13 @@ declare class ToolRegistry {
 }
 
 type ChatEventHandler = (event: ChatEvent) => void;
+/**
+ * Conversations fetched per page, by ``connect`` and ``loadMoreConversations``
+ * alike. The two must use the same size: the offset is derived from how many
+ * rows the server has returned so far, so a first page of a different size
+ * would leave the second page's offset pointing at the wrong row.
+ */
+declare const CONVERSATION_PAGE_SIZE = 50;
 /**
  * ChatSession — translates the backend wire protocol into typed ChatEvents
  * for consumers. Owns HTTP + SSE plumbing, conversation state, and the
@@ -1000,6 +1013,17 @@ declare class ChatSession {
     readonly protocols: ProtocolRegistry<ProtocolAdapter>;
     conversationId: string | null;
     conversations: Conversation[];
+    /**
+     * Whether another page of conversations may exist on the server.
+     *
+     * Inferred from the last page being full, since the list endpoint returns a
+     * bare array with no total. A total that happens to be an exact multiple of
+     * the page size therefore costs one extra empty request before this flips —
+     * cheaper than adding a count query to every list call.
+     */
+    hasMoreConversations: boolean;
+    /** True while ``loadMoreConversations`` is in flight. */
+    isLoadingConversations: boolean;
     messages: Message[];
     isStreaming: boolean;
     agentStatus: AgentStatus | null;
@@ -1007,6 +1031,32 @@ declare class ChatSession {
     skills: SkillInfo[];
     enabledClientTools: Set<string>;
     modelDisplayName: string | null;
+    /**
+     * Ids of conversations the SERVER has handed us, which is the paging offset.
+     *
+     * Deliberately not ``conversations.length``. That array also holds
+     * conversations created locally and unshifted on top (``createNewConversation``,
+     * and the auto-created conversation in ``consumeJobStream``), so using its
+     * length as the offset would over-count and silently skip a row of real
+     * history on the next page. Tracking ids rather than a counter also makes
+     * deletion self-correcting: removing a server-sourced conversation shifts
+     * every later page up by one, and dropping its id from this set is exactly
+     * that shift — while deleting a purely local one correctly changes nothing.
+     */
+    private serverConversationIds;
+    /**
+     * Bumped every time ``connect()`` re-seeds the conversation list.
+     *
+     * A ``loadMoreConversations`` request issued before a re-seed describes the
+     * OLD paging state, so applying its response afterwards both appends the
+     * wrong rows and corrupts the offset. Concretely: with 100 rows held, an
+     * offset-100 response landing after a reconnect has reset to rows 0-49 would
+     * append rows 100-149 — a 50-row hole — and leave the id set at 100, so every
+     * later page re-requests offset 100 and never advances again. The generation
+     * is captured before the await and rechecked after, so a superseded response
+     * is discarded instead.
+     */
+    private conversationsGeneration;
     private accumulatedText;
     private currentTextPath;
     private handlers;
@@ -1095,7 +1145,7 @@ declare class ChatSession {
      * ``message_start`` in the stream (e.g. ``memory_recall`` from prompt prep),
      * so leading with the prompt keeps the turn in order.
      */
-    replayTurn(id: string, events: ConversationEvent[], userMessageContent?: string): void;
+    replayTurn(id: string, events: ConversationEvent[], userMessageContent?: string, userMessageId?: string, isSteer?: boolean): void;
     /**
      * Load a conversation's messages and replay its persisted history.
      *
@@ -1108,6 +1158,40 @@ declare class ChatSession {
      * job's events.
      */
     switchConversation(id: string, jobId?: string): Promise<void>;
+    /**
+     * Append the next page of conversation history to ``conversations``.
+     *
+     * The list is ordered ``updated_at DESC`` and paged by offset, so a
+     * conversation bumped to the top mid-scroll can surface again in a later
+     * page; ids already held are dropped rather than duplicated. Returns only
+     * the conversations actually appended, which may be empty even on a full
+     * page. Rejects on network failure with ``hasMoreConversations`` still true,
+     * so the caller can retry.
+     *
+     * KNOWN LIMITATION — offset paging is only stable while the prefix already
+     * consumed stays put. The offset tracking here corrects for perturbations
+     * THIS session causes (local unshifts, ``deleteConversation``), but not for
+     * ones it never sees:
+     *
+     * - a conversation this session hasn't loaded yet is bumped to the top (a
+     *   headless routine or another device posting to it), pushing the whole
+     *   list down — it lands inside the consumed prefix, which no later offset
+     *   revisits;
+     * - a conversation is deleted from another tab/device, shrinking the list so
+     *   the next offset lands one row too far in.
+     *
+     * Each perturbation costs at most one conversation off the sidebar, and only
+     * until the next ``connect()`` — that re-seeds page 1 and resets the paging
+     * state, so a reload or reconnect always recovers it. Nothing is lost
+     * server-side. Both cases are pinned by tests in
+     * ``tests/conversation-paging.test.ts``.
+     *
+     * Closing the gap properly needs a stable server cursor (keyset paging on
+     * ``(updated_at, id)``) rather than a raw offset, which is a backend change —
+     * tracking ids client-side cannot discover a row that moved into a region
+     * already scanned.
+     */
+    loadMoreConversations(): Promise<Conversation[]>;
     deleteConversation(id: string): Promise<void>;
     toggleClientTool(name: string): boolean;
 }
@@ -1158,26 +1242,6 @@ declare function generateId(): string;
  */
 declare function streamJobSSE(options: StreamJobSSEOptions): AsyncGenerator<ChatStreamEvent>;
 
-/**
- * StreamManager — high-level conversation lifecycle coordinator.
- *
- * Sits on top of ChatSession and manages the state machine for
- * multi-conversation SSE streaming. Framework-agnostic: emits
- * typed events to registered handlers. Block construction is NOT
- * the SDK's concern — consumers build their own block tree from
- * the forwarded ``ChatEvent`` instances.
- *
- *   import { ChatSession, StreamManager } from "@astralform/js";
- *   const session = new ChatSession({ ... });
- *   const manager = new StreamManager(session);
- *   manager.on((event) => {
- *     if (event.type === "event") {
- *       // event.event is a typed ChatEvent — dispatch to your reducer
- *     }
- *   });
- *   await manager.send("Hello");
- */
-
 type StreamState = "idle" | "streaming" | "restoring" | "detached";
 interface SendOptions extends ModelChoiceOptions {
     agentName?: string;
@@ -1340,4 +1404,4 @@ declare function isEmbeddedResource(value: unknown): value is {
  */
 declare function parseEmbeddedResource(value: unknown): EmbeddedResource | null;
 
-export { type ActiveJob, type AgentIdentity, type AgentInfo, type AgentStatus, type AssetCreatedPayload, type AstralformApiKeyConfig, AstralformClient, type AstralformConfig, AstralformError, type AstralformUserTokenConfig, type AttachmentStagedPayload, AuthenticationError, type BlockDeltaPayload, type ChatEvent, ChatEventType, type ChatEventTypeValue, ChatSession, type ChatStorage, type ChatStreamEvent, type ChatStreamRequest, ConnectionError, type ContextUpdatePayload, type ContextWarningPayload, type Conversation, type ConversationAsset, type ConversationEvent, type DesktopStreamPayload, type EmbeddedResource, type FeedbackRequest, type FeedbackResponse, InMemoryStorage, type JobCreateResponse, type JobStatus, type JobSummary, LLMNotConfiguredError, type MemoryRecallPayload, type MemoryRecord, type MemoryUpdatePayload, type Message, type ModelChoiceOptions, type ModelOption, type MyToolGrantsPage, type PromptSuggestionPayload, type ProtocolAdapter, ProtocolRegistry, RateLimitError, type RateLimitErrorDetails, type RawSseEvent, type ReasoningEffort, type SendOptions, ServerError, type SkillInfo, StreamAbortedError, type StreamJobSSEOptions, StreamManager, type StreamManagerEvent, type StreamState, type SubagentStartPayload, type SubagentStopPayload, type TaskStatus, type TeamAgentSummary, type TeamSummary, type TitleGeneratedPayload, type TodoItem, type TodoUpdatePayload, type ToolApprovalDecision, type ToolApprovalGrantedPayload, type ToolApprovalRequest, type ToolApprovalRequestedPayload, type ToolApprovalScope, type ToolCallRequest, type ToolDefinition, type ToolGrant, type ToolHandler, type ToolHarnessWarningPayload, type ToolPermissionDeniedPayload, ToolRegistry, type ToolResult, type ToolResultRequest, type TurnUsage, type UIComponentsConfig, type UserUnavailablePayload, type WireBlockDelta, type WireBlockDeltaPayload, type WireBlockKind, type WireBlockStart, type WireBlockStatus, type WireBlockStop, type WireCustomEvent, type WireErrorEvent, type WireEvent, type WireInputArgDelta, type WireInputDelta, type WireKeepalive, type WireMessageStart, type WireMessageStop, type WireOutputDelta, type WireRetryEvent, type WireSignatureDelta, type WireStallWarning, type WireStatusDelta, type WireStopReason, type WireTextDelta, type WireThinkingDelta, type WorkspaceReadyPayload, generateId, isEmbeddedResource, mapSseToChat, parseEmbeddedResource, replayEvents, streamJobSSE, translateDelta };
+export { type ActiveJob, type AgentIdentity, type AgentInfo, type AgentStatus, type AssetCreatedPayload, type AstralformApiKeyConfig, AstralformClient, type AstralformConfig, AstralformError, type AstralformUserTokenConfig, type AttachmentStagedPayload, AuthenticationError, type BlockDeltaPayload, CONVERSATION_PAGE_SIZE, type ChatEvent, ChatEventType, type ChatEventTypeValue, ChatSession, type ChatStorage, type ChatStreamEvent, type ChatStreamRequest, ConnectionError, type ContextUpdatePayload, type ContextWarningPayload, type Conversation, type ConversationAsset, type ConversationEvent, type DesktopStreamPayload, type EmbeddedResource, type FeedbackRequest, type FeedbackResponse, InMemoryStorage, type JobCreateResponse, type JobStatus, type JobSummary, LLMNotConfiguredError, type MemoryRecallPayload, type MemoryRecord, type MemoryUpdatePayload, type Message, type ModelChoiceOptions, type ModelOption, type MyToolGrantsPage, type PromptSuggestionPayload, type ProtocolAdapter, ProtocolRegistry, RateLimitError, type RateLimitErrorDetails, type RawSseEvent, type ReasoningEffort, type SendOptions, ServerError, type SkillInfo, StreamAbortedError, type StreamJobSSEOptions, StreamManager, type StreamManagerEvent, type StreamState, type SubagentStartPayload, type SubagentStopPayload, type TaskStatus, type TeamAgentSummary, type TeamSummary, type TitleGeneratedPayload, type TodoItem, type TodoUpdatePayload, type ToolApprovalDecision, type ToolApprovalGrantedPayload, type ToolApprovalRequest, type ToolApprovalRequestedPayload, type ToolApprovalScope, type ToolCallRequest, type ToolDefinition, type ToolGrant, type ToolHandler, type ToolHarnessWarningPayload, type ToolPermissionDeniedPayload, ToolRegistry, type ToolResult, type ToolResultRequest, type TurnUsage, type UIComponentsConfig, type UserUnavailablePayload, type WireBlockDelta, type WireBlockDeltaPayload, type WireBlockKind, type WireBlockStart, type WireBlockStatus, type WireBlockStop, type WireCustomEvent, type WireErrorEvent, type WireEvent, type WireInputArgDelta, type WireInputDelta, type WireKeepalive, type WireMessageStart, type WireMessageStop, type WireOutputDelta, type WireRetryEvent, type WireSignatureDelta, type WireStallWarning, type WireStatusDelta, type WireStopReason, type WireTextDelta, type WireThinkingDelta, type WorkspaceReadyPayload, generateId, isEmbeddedResource, mapSseToChat, parseEmbeddedResource, replayEvents, streamJobSSE, translateDelta };

package/dist/index.js

@@ -307,7 +307,7 @@ var AstralformClient = class {
   }
   /**
    * Replace the current OIDC access token without reconstructing the client.
-   * Use after refreshing via the host's token manager (e.g., Supabase JS SDK).
+   * Use after refreshing via the host app's own token manager.
    * Throws if the client was created in API-key mode.
    */
   updateAccessToken(accessToken) {
@@ -1232,6 +1232,7 @@ function translateWireEvent(wire) {
 // src/session.ts
 var SSE_MAX_RECONNECTS = 6;
 var TOOL_RESULT_MAX_RETRIES = 3;
+var CONVERSATION_PAGE_SIZE = 50;
 function sseReconnectDelayMs(attempt) {
   return Math.min(500 * 2 ** (attempt - 1), 5e3);
 }
@@ -1255,6 +1256,17 @@ var ChatSession = class {
     // State
     this.conversationId = null;
     this.conversations = [];
+    /**
+     * Whether another page of conversations may exist on the server.
+     *
+     * Inferred from the last page being full, since the list endpoint returns a
+     * bare array with no total. A total that happens to be an exact multiple of
+     * the page size therefore costs one extra empty request before this flips —
+     * cheaper than adding a count query to every list call.
+     */
+    this.hasMoreConversations = false;
+    /** True while ``loadMoreConversations`` is in flight. */
+    this.isLoadingConversations = false;
     this.messages = [];
     this.isStreaming = false;
     this.agentStatus = null;
@@ -1262,6 +1274,32 @@ var ChatSession = class {
     this.skills = [];
     this.enabledClientTools = /* @__PURE__ */ new Set();
     this.modelDisplayName = null;
+    /**
+     * Ids of conversations the SERVER has handed us, which is the paging offset.
+     *
+     * Deliberately not ``conversations.length``. That array also holds
+     * conversations created locally and unshifted on top (``createNewConversation``,
+     * and the auto-created conversation in ``consumeJobStream``), so using its
+     * length as the offset would over-count and silently skip a row of real
+     * history on the next page. Tracking ids rather than a counter also makes
+     * deletion self-correcting: removing a server-sourced conversation shifts
+     * every later page up by one, and dropping its id from this set is exactly
+     * that shift — while deleting a purely local one correctly changes nothing.
+     */
+    this.serverConversationIds = /* @__PURE__ */ new Set();
+    /**
+     * Bumped every time ``connect()`` re-seeds the conversation list.
+     *
+     * A ``loadMoreConversations`` request issued before a re-seed describes the
+     * OLD paging state, so applying its response afterwards both appends the
+     * wrong rows and corrupts the offset. Concretely: with 100 rows held, an
+     * offset-100 response landing after a reconnect has reset to rows 0-49 would
+     * append rows 100-149 — a 50-row hole — and leave the id set at 100, so every
+     * later page re-requests offset 100 and never advances again. The generation
+     * is captured before the await and rechecked after, so a superseded response
+     * is discarded instead.
+     */
+    this.conversationsGeneration = 0;
     // Minimal in-session accumulation for the assistant message record.
     // Only top-level ``text`` blocks contribute; subagent / tool output
     // is tracked by the consumer's own block store.
@@ -1301,7 +1339,7 @@ var ChatSession = class {
   async connect() {
     const [status, conversations, agents, skills] = await Promise.allSettled([
       this.client.getAgentStatus(),
-      this.client.getConversations(),
+      this.client.getConversations(CONVERSATION_PAGE_SIZE),
       this.client.getAgents().catch(() => []),
       this.client.getSkills().catch(() => [])
     ]);
@@ -1309,7 +1347,12 @@ var ChatSession = class {
       this.agentStatus = status.value;
     }
     if (conversations.status === "fulfilled") {
+      this.conversationsGeneration++;
       this.conversations = conversations.value;
+      this.serverConversationIds = new Set(
+        conversations.value.map((c) => c.id)
+      );
+      this.hasMoreConversations = conversations.value.length === CONVERSATION_PAGE_SIZE;
     }
     if (agents.status === "fulfilled") {
       this.agents = agents.value;
@@ -1730,11 +1773,16 @@ var ChatSession = class {
    * ``message_start`` in the stream (e.g. ``memory_recall`` from prompt prep),
    * so leading with the prompt keeps the turn in order.
    */
-  replayTurn(id, events, userMessageContent) {
+  replayTurn(id, events, userMessageContent, userMessageId, isSteer = false) {
     this.conversationId = id;
     this.resetStreamingState();
     if (userMessageContent) {
-      this.emit({ type: "user_message", content: userMessageContent });
+      this.emit({
+        type: "user_message",
+        content: userMessageContent,
+        ...userMessageId ? { id: userMessageId } : {},
+        ...isSteer ? { steer: true } : {}
+      });
     }
     for (const ev of events) {
       const type = ev.data.type || ev.event;
@@ -1768,12 +1816,69 @@ var ChatSession = class {
       eventsResult.status === "fulfilled" ? eventsResult.value : []
     );
   }
+  /**
+   * Append the next page of conversation history to ``conversations``.
+   *
+   * The list is ordered ``updated_at DESC`` and paged by offset, so a
+   * conversation bumped to the top mid-scroll can surface again in a later
+   * page; ids already held are dropped rather than duplicated. Returns only
+   * the conversations actually appended, which may be empty even on a full
+   * page. Rejects on network failure with ``hasMoreConversations`` still true,
+   * so the caller can retry.
+   *
+   * KNOWN LIMITATION — offset paging is only stable while the prefix already
+   * consumed stays put. The offset tracking here corrects for perturbations
+   * THIS session causes (local unshifts, ``deleteConversation``), but not for
+   * ones it never sees:
+   *
+   * - a conversation this session hasn't loaded yet is bumped to the top (a
+   *   headless routine or another device posting to it), pushing the whole
+   *   list down — it lands inside the consumed prefix, which no later offset
+   *   revisits;
+   * - a conversation is deleted from another tab/device, shrinking the list so
+   *   the next offset lands one row too far in.
+   *
+   * Each perturbation costs at most one conversation off the sidebar, and only
+   * until the next ``connect()`` — that re-seeds page 1 and resets the paging
+   * state, so a reload or reconnect always recovers it. Nothing is lost
+   * server-side. Both cases are pinned by tests in
+   * ``tests/conversation-paging.test.ts``.
+   *
+   * Closing the gap properly needs a stable server cursor (keyset paging on
+   * ``(updated_at, id)``) rather than a raw offset, which is a backend change —
+   * tracking ids client-side cannot discover a row that moved into a region
+   * already scanned.
+   */
+  async loadMoreConversations() {
+    if (this.isLoadingConversations || !this.hasMoreConversations) return [];
+    this.isLoadingConversations = true;
+    const generation = this.conversationsGeneration;
+    try {
+      const page = await this.client.getConversations(
+        CONVERSATION_PAGE_SIZE,
+        this.serverConversationIds.size
+      );
+      if (generation !== this.conversationsGeneration) return [];
+      this.hasMoreConversations = page.length === CONVERSATION_PAGE_SIZE;
+      const fresh = page.filter((c) => !this.serverConversationIds.has(c.id));
+      for (const c of page) this.serverConversationIds.add(c.id);
+      const known = new Set(this.conversations.map((c) => c.id));
+      const appended = fresh.filter((c) => !known.has(c.id));
+      this.conversations.push(...appended);
+      return appended;
+    } finally {
+      this.isLoadingConversations = false;
+    }
+  }
   async deleteConversation(id) {
     try {
       await this.client.deleteConversation(id);
     } catch {
     }
     await this.storage.deleteConversation(id);
+    if (this.serverConversationIds.delete(id)) {
+      this.conversationsGeneration++;
+    }
     this.conversations = this.conversations.filter((c) => c.id !== id);
     if (this.conversationId === id) {
       this.conversationId = null;
@@ -1790,6 +1895,64 @@ var ChatSession = class {
   }
 };
 
+// src/restore-plan.ts
+function planRestore(args) {
+  const { completedJobs, userMessages } = args;
+  const byId = /* @__PURE__ */ new Map();
+  userMessages.forEach((m, i) => {
+    if (m.id) byId.set(m.id, i);
+  });
+  const linkOf = (j) => j.message_id ? byId.get(j.message_id) : void 0;
+  const positional = (jobs, msgs) => jobs.map((job, i) => ({
+    kind: "turn",
+    jobId: job.job_id,
+    content: msgs[i]?.content,
+    messageId: msgs[i]?.id
+  }));
+  const firstLinked = completedJobs.findIndex((j) => linkOf(j) !== void 0);
+  if (firstLinked === -1) {
+    return positional(completedJobs, userMessages);
+  }
+  const cutover = linkOf(completedJobs[firstLinked]);
+  const steps = positional(
+    completedJobs.slice(0, firstLinked),
+    userMessages.slice(0, cutover)
+  );
+  let cursor = cutover;
+  const isSteer = (m) => !!m?.id && !completedJobs.some((j) => j.message_id === m.id);
+  const drainTo = (stopAt) => {
+    while (cursor < stopAt) {
+      const m = userMessages[cursor++];
+      if (isSteer(m)) {
+        steps.push({ kind: "steer", content: m.content, messageId: m.id });
+      }
+    }
+    cursor = stopAt + 1;
+  };
+  for (const job of completedJobs.slice(firstLinked)) {
+    const at = linkOf(job);
+    if (at !== void 0) {
+      drainTo(at);
+      const prompt = userMessages[at];
+      steps.push({
+        kind: "turn",
+        jobId: job.job_id,
+        content: prompt.content,
+        messageId: prompt.id
+      });
+      continue;
+    }
+    steps.push({ kind: "turn", jobId: job.job_id });
+  }
+  for (let i = cursor; i < userMessages.length; i++) {
+    const m = userMessages[i];
+    if (isSteer(m)) {
+      steps.push({ kind: "steer", content: m.content, messageId: m.id });
+    }
+  }
+  return steps;
+}
+
 // src/types.ts
 var ChatEventType = {
   // Connection lifecycle (SDK-local, not wire)
@@ -2058,16 +2221,40 @@ var StreamManager = class {
         const userMessages = this.session.messages.filter(
           (m) => m.role === "user"
         );
+        const plan = planRestore({
+          completedJobs: completedJobs.map((j) => ({
+            job_id: j.job_id,
+            message_id: j.message_id
+          })),
+          userMessages: userMessages.map((m) => ({
+            id: m.id,
+            content: m.content
+          }))
+        });
         const eventLists = await Promise.all(
           completedJobs.map(
             (job) => this.session.client.getConversationEvents(conversationId, job.job_id).catch(() => [])
           )
         );
-        for (let i = 0; i < completedJobs.length; i++) {
+        const eventsByJobId = new Map(
+          completedJobs.map((job, i) => [job.job_id, eventLists[i] ?? []])
+        );
+        for (const step of plan) {
+          if (step.kind === "steer") {
+            this.session.replayTurn(
+              conversationId,
+              [],
+              step.content,
+              step.messageId,
+              true
+            );
+            continue;
+          }
           this.session.replayTurn(
             conversationId,
-            eventLists[i] ?? [],
-            userMessages[i]?.content
+            eventsByJobId.get(step.jobId) ?? [],
+            step.content,
+            step.messageId
           );
         }
         if (completedJobs.length > 0) {
@@ -2158,6 +2345,7 @@ export {
   AstralformClient,
   AstralformError,
   AuthenticationError,
+  CONVERSATION_PAGE_SIZE,
   ChatEventType,
   ChatSession,
   ConnectionError,