@astralform/js 4.9.0 → 5.0.0

package/dist/index.d.cts

@@ -792,6 +792,24 @@ interface ConversationEvent {
     data: Record<string, unknown>;
 }
 interface SendOptions$1 extends ModelChoiceOptions {
+    /**
+     * Which conversation this turn belongs to. Defaults to the session's current
+     * one.
+     *
+     * ⚠️ BEHAVIOR CHANGE: passing this now RELOCATES the session. A value
+     * different from the current one sets `session.conversationId`, DISCARDS
+     * `session.messages` (the old conversation's list is not that conversation's
+     * history), and invalidates any `loadConversation` still in flight.
+     * Previously it addressed a single turn elsewhere and left the session where
+     * it was. After a successful send the list holds only that turn, so load the
+     * conversation if you need its history.
+     *
+     * The change is deliberate: `onSessionEvent` tags every emitted event with
+     * `session.conversationId`, so a turn sent elsewhere without moving the
+     * pointer streamed its events back under the wrong conversation. Addressing
+     * one turn away from the session is not something the session can honestly
+     * represent while it has a single pointer, so the send now moves it.
+     */
     conversationId?: string;
     enabledClientTools?: string[];
     uploadIds?: string[];
@@ -1115,6 +1133,17 @@ declare class ChatSession {
     /** True while ``loadMoreConversations`` is in flight. */
     isLoadingConversations: boolean;
     messages: Message[];
+    /**
+     * Which conversation ``messages`` currently holds.
+     *
+     * Distinct from ``conversationId``, and the distinction is the point:
+     * ``loadConversation`` moves the POINTER synchronously and installs the LIST
+     * an await later, so for the whole duration of every load the two disagree.
+     * Anything pairing a message with a conversation — ``regenerate`` above all —
+     * has to read this one, or it will pair the previous conversation's last
+     * message with the new conversation's id.
+     */
+    messagesConversationId: string | null;
     isStreaming: boolean;
     agentStatus: AgentStatus | null;
     agents: AgentInfo[];
@@ -1147,6 +1176,49 @@ declare class ChatSession {
      * is discarded instead.
      */
     private conversationsGeneration;
+    /**
+     * Bumped by every ``loadConversation`` call, so an out-of-order fetch can
+     * tell it is no longer the newest one and drop its result. Separate from
+     * ``conversationsGeneration``, which guards the conversation LIST.
+     */
+    private loadGeneration;
+    /**
+     * Ids of locally-created user messages the server has not acknowledged yet.
+     *
+     * Arrival time cannot answer "could the reply have included this?" on its
+     * own. Every `loadConversation` in `StreamManager` sits behind the
+     * active-job probe, so the ORDINARY ordering is that a send lands BEFORE the
+     * load starts — and an arrival-time rule drops exactly those, losing the
+     * prompt the user just sent while its stream is still running. Membership
+     * here is set by `send` and cleared when a server row turns up carrying the
+     * same turn, so the keep-decision no longer depends on which side of the
+     * fetch the push landed on.
+     *
+     * The value is `serverRowsKnown` as of the `message_stop` that proved the
+     * row committed, or 0 until then — including after the job response, which
+     * hands back the id but starts the loop as a background task and so proves
+     * nothing about the row. That stamp is what separates "the snapshot predates
+     * the row" from "the server does not have this row" — see
+     * `loadConversation`.
+     *
+     * It is an ANNOTATION ON `this.messages`: reconciliation only ever consults
+     * entries of that array, so an id whose message has left it is dead weight.
+     * `setMessages` is the single place the array is replaced, and it prunes.
+     */
+    private pendingUserMessages;
+    /**
+     * Bumped once per completed turn, at `message_stop`, so a fetch can record
+     * what was proven when it was ISSUED. A row proven committed before the
+     * fetch went out must appear in its snapshot; one proven after may
+     * legitimately be missing.
+     */
+    private serverRowsKnown;
+    /**
+     * Replace the message list, keeping `pendingUserMessages` an annotation on
+     * it. Every removal from the array goes through here — `push` is the only
+     * other mutation and it cannot orphan an id.
+     */
+    private setMessages;
     private accumulatedText;
     private currentTextPath;
     private handlers;
@@ -1180,6 +1252,11 @@ declare class ChatSession {
      * Consume a single SSE stream to exhaustion. Returns whether a terminal
      * event (``message_stop`` / ``error``) was seen, so the caller can decide
      * whether an ended stream means "turn done" vs "dropped, reconnect".
+     *
+     * ``onStall`` aborts the per-attempt connection: if no event arrives within
+     * SSE_STALL_TIMEOUT_MS (backend keepalives land every 15s), the stream is a
+     * zombie — ``reader.read()`` will never settle — so we kill the fetch and
+     * throw a ConnectionError, feeding the caller's reconnect-from-lastSeq loop.
      */
     private pumpStream;
     /** Sleep for ``ms``, resolving early if the turn is aborted mid-backoff. */
@@ -1200,9 +1277,15 @@ declare class ChatSession {
      * the pure wire → ChatEvent mapping can live in translate.ts and be reused
      * by the replay path.
      *
-     * ``messageId`` is the server-assigned assistant message id for the current
-     * turn; empty in the reconnect and conversation-switch replay paths where
-     * messages have already been loaded from REST and shouldn't be re-pushed.
+     * ``promptMessageId`` is the id of the USER turn that started this job —
+     * `POST /v1/jobs` returns it and the backend tags the prompt with it
+     * (`HumanMessage(content=..., id=message_id)`), which is what lets a restore
+     * pair a job with its prompt by id instead of by position. It was previously
+     * documented here as the ASSISTANT's id and used as one; there is no
+     * server-assigned assistant id on the wire, so that row gets a local one.
+     * Empty in the reconnect and conversation-switch replay paths, where the
+     * messages have already been loaded from REST and must not be re-pushed —
+     * so it doubles as the "is this a live send?" gate.
      */
     private applyWireSideEffects;
     private executeClientTools;
@@ -1218,8 +1301,26 @@ declare class ChatSession {
     reconnectToJob(jobId: string): Promise<void>;
     /** Detach from the SSE stream without cancelling the job. */
     detach(): void;
-    /** Stop the job and disconnect (explicit user action). */
+    /**
+     * Cancel the running turn: stop the job server-side and tear the stream
+     * down, WITHOUT ending the session. A turn-level cancel is not a
+     * session-level teardown, so unlike `disconnect()` this leaves the protocol
+     * registry alone — the SDK never auto-registers adapters, so clearing them
+     * on a Stop press would silently kill embedded-resource rendering for the
+     * rest of the session with nothing to re-register it.
+     */
+    cancelTurn(): void;
+    /** Stop the job and end the session's activity (explicit user action). */
     disconnect(): void;
+    /**
+     * A pointer move happened above this layer, so any `loadConversation` in
+     * flight must lose to it. `StreamManager` owns a pointer of its own and
+     * moves it before this one; without this the two halves would gate on
+     * counters that bump at different instants — `generation` synchronously in
+     * `setActiveConversation`, `loadGeneration` only once the switch's own load
+     * actually runs, which is behind the active-job probe.
+     */
+    invalidateLoadsInFlight(): void;
     createNewConversation(): Promise<string>;
     /**
      * Replay one completed turn's already-fetched events, synchronously.
@@ -1396,6 +1497,12 @@ declare class StreamManager {
     private _backgroundJobs;
     private handlers;
     private unsub;
+    /**
+     * Bumped every time the active conversation moves. An async sequence that
+     * captures it can then tell, at each await boundary, whether it is still the
+     * one the user is waiting on — see ``restore``.
+     */
+    private generation;
     constructor(session: ChatSession);
     get state(): StreamState;
     get activeConversationId(): string | null;
@@ -1427,6 +1534,15 @@ declare class StreamManager {
     switchTo(conversationId: string, opts?: {
         skipHistoryReplay?: boolean;
     }): Promise<void>;
+    /**
+     * Create a conversation and make it active.
+     *
+     * The returned id is NOT guaranteed to be the active conversation: if a
+     * switch lands inside the storage round-trip, this declines the pointer move
+     * so the newer one wins, and no `conversationChanged` fires for the new id.
+     * A caller that routes on the return value should `switchTo(id)` rather than
+     * assume it is current — that call is not a no-op in the declined case.
+     */
     createConversation(): Promise<string>;
     /**
      * Rename a conversation. Purely a relabel — no active-conversation or
@@ -1436,6 +1552,31 @@ declare class StreamManager {
     deleteConversation(id: string): Promise<void>;
     stop(): void;
     destroy(): void;
+    /**
+     * Park a streaming turn as a background job and detach from its SSE stream.
+     *
+     * Every method that relocates the active conversation has to do this before
+     * announcing a new state. Announcing `idle` while `session.isStreaming` is
+     * still true is worse than announcing nothing: `manager.send` no longer bails
+     * on the streaming state, calls `session.send`, and THAT bails on its own
+     * `isStreaming` — so the message is never posted, no error is emitted, and
+     * the composer looks ready the whole time.
+     */
+    private detachStreamingTurn;
+    /**
+     * Announce `idle` unless a turn is actually streaming.
+     *
+     * A `send` can land inside any of the switch paths — the fast path most
+     * easily, since it deliberately stays out of `restoring` and so leaves the
+     * composer live for the whole probe. `send` sets `streaming` and does not
+     * bump the generation, so the path resumes, passes its supersession check,
+     * and would announce a ready composer over a running stream. From there
+     * `finalizeStream` and the `message_stop` branch both no-op (they only act
+     * on `streaming`), so it stays `idle` for the whole turn — and the next send
+     * reaches `session.send`, which bails on its own `isStreaming`: message
+     * never posted, no error, composer ready throughout.
+     */
+    private settleIdle;
     private finalizeStream;
     private restore;
     private setActiveConversation;

package/dist/index.d.ts

@@ -792,6 +792,24 @@ interface ConversationEvent {
     data: Record<string, unknown>;
 }
 interface SendOptions$1 extends ModelChoiceOptions {
+    /**
+     * Which conversation this turn belongs to. Defaults to the session's current
+     * one.
+     *
+     * ⚠️ BEHAVIOR CHANGE: passing this now RELOCATES the session. A value
+     * different from the current one sets `session.conversationId`, DISCARDS
+     * `session.messages` (the old conversation's list is not that conversation's
+     * history), and invalidates any `loadConversation` still in flight.
+     * Previously it addressed a single turn elsewhere and left the session where
+     * it was. After a successful send the list holds only that turn, so load the
+     * conversation if you need its history.
+     *
+     * The change is deliberate: `onSessionEvent` tags every emitted event with
+     * `session.conversationId`, so a turn sent elsewhere without moving the
+     * pointer streamed its events back under the wrong conversation. Addressing
+     * one turn away from the session is not something the session can honestly
+     * represent while it has a single pointer, so the send now moves it.
+     */
     conversationId?: string;
     enabledClientTools?: string[];
     uploadIds?: string[];
@@ -1115,6 +1133,17 @@ declare class ChatSession {
     /** True while ``loadMoreConversations`` is in flight. */
     isLoadingConversations: boolean;
     messages: Message[];
+    /**
+     * Which conversation ``messages`` currently holds.
+     *
+     * Distinct from ``conversationId``, and the distinction is the point:
+     * ``loadConversation`` moves the POINTER synchronously and installs the LIST
+     * an await later, so for the whole duration of every load the two disagree.
+     * Anything pairing a message with a conversation — ``regenerate`` above all —
+     * has to read this one, or it will pair the previous conversation's last
+     * message with the new conversation's id.
+     */
+    messagesConversationId: string | null;
     isStreaming: boolean;
     agentStatus: AgentStatus | null;
     agents: AgentInfo[];
@@ -1147,6 +1176,49 @@ declare class ChatSession {
      * is discarded instead.
      */
     private conversationsGeneration;
+    /**
+     * Bumped by every ``loadConversation`` call, so an out-of-order fetch can
+     * tell it is no longer the newest one and drop its result. Separate from
+     * ``conversationsGeneration``, which guards the conversation LIST.
+     */
+    private loadGeneration;
+    /**
+     * Ids of locally-created user messages the server has not acknowledged yet.
+     *
+     * Arrival time cannot answer "could the reply have included this?" on its
+     * own. Every `loadConversation` in `StreamManager` sits behind the
+     * active-job probe, so the ORDINARY ordering is that a send lands BEFORE the
+     * load starts — and an arrival-time rule drops exactly those, losing the
+     * prompt the user just sent while its stream is still running. Membership
+     * here is set by `send` and cleared when a server row turns up carrying the
+     * same turn, so the keep-decision no longer depends on which side of the
+     * fetch the push landed on.
+     *
+     * The value is `serverRowsKnown` as of the `message_stop` that proved the
+     * row committed, or 0 until then — including after the job response, which
+     * hands back the id but starts the loop as a background task and so proves
+     * nothing about the row. That stamp is what separates "the snapshot predates
+     * the row" from "the server does not have this row" — see
+     * `loadConversation`.
+     *
+     * It is an ANNOTATION ON `this.messages`: reconciliation only ever consults
+     * entries of that array, so an id whose message has left it is dead weight.
+     * `setMessages` is the single place the array is replaced, and it prunes.
+     */
+    private pendingUserMessages;
+    /**
+     * Bumped once per completed turn, at `message_stop`, so a fetch can record
+     * what was proven when it was ISSUED. A row proven committed before the
+     * fetch went out must appear in its snapshot; one proven after may
+     * legitimately be missing.
+     */
+    private serverRowsKnown;
+    /**
+     * Replace the message list, keeping `pendingUserMessages` an annotation on
+     * it. Every removal from the array goes through here — `push` is the only
+     * other mutation and it cannot orphan an id.
+     */
+    private setMessages;
     private accumulatedText;
     private currentTextPath;
     private handlers;
@@ -1180,6 +1252,11 @@ declare class ChatSession {
      * Consume a single SSE stream to exhaustion. Returns whether a terminal
      * event (``message_stop`` / ``error``) was seen, so the caller can decide
      * whether an ended stream means "turn done" vs "dropped, reconnect".
+     *
+     * ``onStall`` aborts the per-attempt connection: if no event arrives within
+     * SSE_STALL_TIMEOUT_MS (backend keepalives land every 15s), the stream is a
+     * zombie — ``reader.read()`` will never settle — so we kill the fetch and
+     * throw a ConnectionError, feeding the caller's reconnect-from-lastSeq loop.
      */
     private pumpStream;
     /** Sleep for ``ms``, resolving early if the turn is aborted mid-backoff. */
@@ -1200,9 +1277,15 @@ declare class ChatSession {
      * the pure wire → ChatEvent mapping can live in translate.ts and be reused
      * by the replay path.
      *
-     * ``messageId`` is the server-assigned assistant message id for the current
-     * turn; empty in the reconnect and conversation-switch replay paths where
-     * messages have already been loaded from REST and shouldn't be re-pushed.
+     * ``promptMessageId`` is the id of the USER turn that started this job —
+     * `POST /v1/jobs` returns it and the backend tags the prompt with it
+     * (`HumanMessage(content=..., id=message_id)`), which is what lets a restore
+     * pair a job with its prompt by id instead of by position. It was previously
+     * documented here as the ASSISTANT's id and used as one; there is no
+     * server-assigned assistant id on the wire, so that row gets a local one.
+     * Empty in the reconnect and conversation-switch replay paths, where the
+     * messages have already been loaded from REST and must not be re-pushed —
+     * so it doubles as the "is this a live send?" gate.
      */
     private applyWireSideEffects;
     private executeClientTools;
@@ -1218,8 +1301,26 @@ declare class ChatSession {
     reconnectToJob(jobId: string): Promise<void>;
     /** Detach from the SSE stream without cancelling the job. */
     detach(): void;
-    /** Stop the job and disconnect (explicit user action). */
+    /**
+     * Cancel the running turn: stop the job server-side and tear the stream
+     * down, WITHOUT ending the session. A turn-level cancel is not a
+     * session-level teardown, so unlike `disconnect()` this leaves the protocol
+     * registry alone — the SDK never auto-registers adapters, so clearing them
+     * on a Stop press would silently kill embedded-resource rendering for the
+     * rest of the session with nothing to re-register it.
+     */
+    cancelTurn(): void;
+    /** Stop the job and end the session's activity (explicit user action). */
     disconnect(): void;
+    /**
+     * A pointer move happened above this layer, so any `loadConversation` in
+     * flight must lose to it. `StreamManager` owns a pointer of its own and
+     * moves it before this one; without this the two halves would gate on
+     * counters that bump at different instants — `generation` synchronously in
+     * `setActiveConversation`, `loadGeneration` only once the switch's own load
+     * actually runs, which is behind the active-job probe.
+     */
+    invalidateLoadsInFlight(): void;
     createNewConversation(): Promise<string>;
     /**
      * Replay one completed turn's already-fetched events, synchronously.
@@ -1396,6 +1497,12 @@ declare class StreamManager {
     private _backgroundJobs;
     private handlers;
     private unsub;
+    /**
+     * Bumped every time the active conversation moves. An async sequence that
+     * captures it can then tell, at each await boundary, whether it is still the
+     * one the user is waiting on — see ``restore``.
+     */
+    private generation;
     constructor(session: ChatSession);
     get state(): StreamState;
     get activeConversationId(): string | null;
@@ -1427,6 +1534,15 @@ declare class StreamManager {
     switchTo(conversationId: string, opts?: {
         skipHistoryReplay?: boolean;
     }): Promise<void>;
+    /**
+     * Create a conversation and make it active.
+     *
+     * The returned id is NOT guaranteed to be the active conversation: if a
+     * switch lands inside the storage round-trip, this declines the pointer move
+     * so the newer one wins, and no `conversationChanged` fires for the new id.
+     * A caller that routes on the return value should `switchTo(id)` rather than
+     * assume it is current — that call is not a no-op in the declined case.
+     */
     createConversation(): Promise<string>;
     /**
      * Rename a conversation. Purely a relabel — no active-conversation or
@@ -1436,6 +1552,31 @@ declare class StreamManager {
     deleteConversation(id: string): Promise<void>;
     stop(): void;
     destroy(): void;
+    /**
+     * Park a streaming turn as a background job and detach from its SSE stream.
+     *
+     * Every method that relocates the active conversation has to do this before
+     * announcing a new state. Announcing `idle` while `session.isStreaming` is
+     * still true is worse than announcing nothing: `manager.send` no longer bails
+     * on the streaming state, calls `session.send`, and THAT bails on its own
+     * `isStreaming` — so the message is never posted, no error is emitted, and
+     * the composer looks ready the whole time.
+     */
+    private detachStreamingTurn;
+    /**
+     * Announce `idle` unless a turn is actually streaming.
+     *
+     * A `send` can land inside any of the switch paths — the fast path most
+     * easily, since it deliberately stays out of `restoring` and so leaves the
+     * composer live for the whole probe. `send` sets `streaming` and does not
+     * bump the generation, so the path resumes, passes its supersession check,
+     * and would announce a ready composer over a running stream. From there
+     * `finalizeStream` and the `message_stop` branch both no-op (they only act
+     * on `streaming`), so it stays `idle` for the whole turn — and the next send
+     * reaches `session.send`, which bails on its own `isStreaming`: message
+     * never posted, no error, composer ready throughout.
+     */
+    private settleIdle;
     private finalizeStream;
     private restore;
     private setActiveConversation;