@astralform/js 4.1.0 → 4.3.0

package/dist/index.d.cts

@@ -120,6 +120,19 @@ interface AstralformBaseConfig {
     baseURL?: string;
     /** Supply a custom fetch (SSR, testing, custom interceptors). */
     fetch?: typeof globalThis.fetch;
+    /**
+     * Abort a REST request — connect, headers, AND body read — after this many
+     * milliseconds. Defaults to 30_000. Does not apply to `uploadFile` (large
+     * files on slow uplinks) or to SSE streaming, which is long-lived by design
+     * and carries its own `AbortSignal`.
+     *
+     * Note that unlike axios and friends, `0` does NOT mean "no timeout": any
+     * non-positive or non-finite value falls back to the default. REST calls
+     * cannot opt out of the deadline — an unbounded REST request is the bug
+     * this exists to prevent, and it fails silently (a stalled body strands the
+     * caller forever with nothing to react to).
+     */
+    timeoutMs?: number;
 }
 interface AstralformApiKeyConfig extends AstralformBaseConfig {
     /** Agent API key (`sk_live_...` or `sk_test_...`). */
@@ -773,6 +786,7 @@ interface ConversationAsset {
 declare class AstralformClient {
     private readonly baseURL;
     private readonly fetchFn;
+    private readonly timeoutMs;
     /**
      * Auth state is mutable so callers can rotate access tokens or switch
      * agent context without re-instantiating the client. API-key mode is
@@ -782,7 +796,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;
@@ -819,7 +833,23 @@ declare class AstralformClient {
      */
     private get authHeaders();
     private get headers();
+    /**
+     * Run one REST exchange under a single deadline covering connect, headers,
+     * AND the body read. The body read is the part that matters: `json()` used
+     * to sit outside every guard, so a response whose headers arrived but whose
+     * body stalled hung forever — silently stranding callers that await it
+     * (a stalled `getMessages` used to leave `StreamManager.restore()` parked
+     * before it ever fetched the events it renders from).
+     *
+     * The controller is created per request and is deliberately NOT the
+     * session's — that one means "the user cancelled this turn" and is null
+     * outside a live turn. Aborting frees the socket; the race guarantees a
+     * rejection even when an injected `fetch` ignores the signal.
+     */
+    private withDeadline;
     private request;
+    /** Fetch + status handling. Always called inside `withDeadline`. */
+    private send;
     get<T>(path: string): Promise<T>;
     post<T>(path: string, body: unknown): Promise<T>;
     private del;
@@ -950,6 +980,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
@@ -970,6 +1007,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;
@@ -977,6 +1025,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;
@@ -1078,6 +1152,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;
 }
@@ -1310,4 +1418,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

@@ -120,6 +120,19 @@ interface AstralformBaseConfig {
     baseURL?: string;
     /** Supply a custom fetch (SSR, testing, custom interceptors). */
     fetch?: typeof globalThis.fetch;
+    /**
+     * Abort a REST request — connect, headers, AND body read — after this many
+     * milliseconds. Defaults to 30_000. Does not apply to `uploadFile` (large
+     * files on slow uplinks) or to SSE streaming, which is long-lived by design
+     * and carries its own `AbortSignal`.
+     *
+     * Note that unlike axios and friends, `0` does NOT mean "no timeout": any
+     * non-positive or non-finite value falls back to the default. REST calls
+     * cannot opt out of the deadline — an unbounded REST request is the bug
+     * this exists to prevent, and it fails silently (a stalled body strands the
+     * caller forever with nothing to react to).
+     */
+    timeoutMs?: number;
 }
 interface AstralformApiKeyConfig extends AstralformBaseConfig {
     /** Agent API key (`sk_live_...` or `sk_test_...`). */
@@ -773,6 +786,7 @@ interface ConversationAsset {
 declare class AstralformClient {
     private readonly baseURL;
     private readonly fetchFn;
+    private readonly timeoutMs;
     /**
      * Auth state is mutable so callers can rotate access tokens or switch
      * agent context without re-instantiating the client. API-key mode is
@@ -782,7 +796,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;
@@ -819,7 +833,23 @@ declare class AstralformClient {
      */
     private get authHeaders();
     private get headers();
+    /**
+     * Run one REST exchange under a single deadline covering connect, headers,
+     * AND the body read. The body read is the part that matters: `json()` used
+     * to sit outside every guard, so a response whose headers arrived but whose
+     * body stalled hung forever — silently stranding callers that await it
+     * (a stalled `getMessages` used to leave `StreamManager.restore()` parked
+     * before it ever fetched the events it renders from).
+     *
+     * The controller is created per request and is deliberately NOT the
+     * session's — that one means "the user cancelled this turn" and is null
+     * outside a live turn. Aborting frees the socket; the race guarantees a
+     * rejection even when an injected `fetch` ignores the signal.
+     */
+    private withDeadline;
     private request;
+    /** Fetch + status handling. Always called inside `withDeadline`. */
+    private send;
     get<T>(path: string): Promise<T>;
     post<T>(path: string, body: unknown): Promise<T>;
     private del;
@@ -950,6 +980,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
@@ -970,6 +1007,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;
@@ -977,6 +1025,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;
@@ -1078,6 +1152,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;
 }
@@ -1310,4 +1418,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

@@ -252,6 +252,7 @@ async function* streamJobSSE(options) {
 
 // src/client.ts
 var DEFAULT_BASE_URL = "https://api.astralform.ai";
+var DEFAULT_TIMEOUT_MS = 3e4;
 function validateBaseURL(url) {
   const cleaned = url.replace(/\/+$/, "");
   try {
@@ -302,10 +303,11 @@ var AstralformClient = class {
     }
     this.baseURL = validateBaseURL(config.baseURL ?? DEFAULT_BASE_URL);
     this.fetchFn = config.fetch ?? globalThis.fetch.bind(globalThis);
+    this.timeoutMs = typeof config.timeoutMs === "number" && Number.isFinite(config.timeoutMs) && config.timeoutMs > 0 ? config.timeoutMs : DEFAULT_TIMEOUT_MS;
   }
   /**
    * 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) {
@@ -392,11 +394,48 @@ var AstralformClient = class {
       "Content-Type": "application/json"
     };
   }
+  /**
+   * Run one REST exchange under a single deadline covering connect, headers,
+   * AND the body read. The body read is the part that matters: `json()` used
+   * to sit outside every guard, so a response whose headers arrived but whose
+   * body stalled hung forever — silently stranding callers that await it
+   * (a stalled `getMessages` used to leave `StreamManager.restore()` parked
+   * before it ever fetched the events it renders from).
+   *
+   * The controller is created per request and is deliberately NOT the
+   * session's — that one means "the user cancelled this turn" and is null
+   * outside a live turn. Aborting frees the socket; the race guarantees a
+   * rejection even when an injected `fetch` ignores the signal.
+   */
+  async withDeadline(run) {
+    const controller = new AbortController();
+    const timedOut = () => new ConnectionError(`Request timed out after ${this.timeoutMs}ms`);
+    let timer;
+    const deadline = new Promise((_resolve, reject) => {
+      timer = setTimeout(() => {
+        controller.abort();
+        reject(timedOut());
+      }, this.timeoutMs);
+    });
+    try {
+      return await Promise.race([run(controller.signal), deadline]);
+    } catch (err) {
+      if (controller.signal.aborted) throw timedOut();
+      throw err;
+    } finally {
+      clearTimeout(timer);
+    }
+  }
   async request(method, path, body) {
+    return this.withDeadline((signal) => this.send(method, path, body, signal));
+  }
+  /** Fetch + status handling. Always called inside `withDeadline`. */
+  async send(method, path, body, signal) {
     const response = await this.fetchFn(`${this.baseURL}${path}`, {
       method,
       headers: this.headers,
-      body: body !== void 0 ? JSON.stringify(body) : void 0
+      body: body !== void 0 ? JSON.stringify(body) : void 0,
+      signal
     }).catch((err) => {
       throw new ConnectionError(
         err instanceof Error ? err.message : "Failed to connect"
@@ -405,13 +444,21 @@ var AstralformClient = class {
     await this.handleError(response);
     return response;
   }
+  // DO NOT refactor these back into `request()` + `.json()`. Parsing the body
+  // INSIDE the raced callback is the entire fix: `json()` outside the deadline
+  // is the original bug (headers arrive, body stalls, caller hangs forever).
+  // `request()` survives for `del()`, which never reads the body.
   async get(path) {
-    const response = await this.request("GET", path);
-    return response.json();
+    return this.withDeadline(async (signal) => {
+      const response = await this.send("GET", path, void 0, signal);
+      return await response.json();
+    });
   }
   async post(path, body) {
-    const response = await this.request("POST", path, body);
-    return response.json();
+    return this.withDeadline(async (signal) => {
+      const response = await this.send("POST", path, body, signal);
+      return await response.json();
+    });
   }
   async del(path) {
     await this.request("DELETE", path);
@@ -1185,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);
 }
@@ -1208,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;
@@ -1215,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.
@@ -1254,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(() => [])
     ]);
@@ -1262,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;
@@ -1721,12 +1811,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;
@@ -2111,6 +2258,7 @@ export {
   AstralformClient,
   AstralformError,
   AuthenticationError,
+  CONVERSATION_PAGE_SIZE,
   ChatEventType,
   ChatSession,
   ConnectionError,