@astralform/js 8.0.0 → 8.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.d.ts CHANGED
@@ -73,6 +73,15 @@ interface MemoryUpdatePayload {
73
73
  key?: string | null;
74
74
  namespace?: string | null;
75
75
  }
76
+ interface MemoryProviderErrorPayload {
77
+ /** The external memory provider that failed (registry slug, e.g. "mem0"). */
78
+ provider: string;
79
+ /** Which provider operation failed — "save" | "update" | "delete" | "get"
80
+ * | "recall" | "ingest" | "list_visible" | … Typed as string for forward compat. */
81
+ op: string;
82
+ /** One-line "<ExceptionType>: <message>" detail, length-capped by the backend. */
83
+ error: string;
84
+ }
76
85
  interface DesktopStreamPayload {
77
86
  url: string;
78
87
  sandboxId?: string | null;
@@ -117,6 +126,38 @@ interface ToolHarnessWarningPayload {
117
126
  message?: string | null;
118
127
  details?: Record<string, unknown> | null;
119
128
  }
129
+ interface ToolProgressPayload {
130
+ callId: string;
131
+ /** Known values: "stdout" | "stderr" | "progress" | "command". Typed as string
132
+ * for forward compat; the backend defaults to "progress". */
133
+ stream: string;
134
+ /** Live progress text to append; the backend newline-terminates chunks. */
135
+ chunk: string;
136
+ /** Emitting tool, e.g. "web_search" | "deep_research" | "generate_video".
137
+ * Wire key is `tool`; camelCase here, like the rest of this catalog. */
138
+ toolName?: string | null;
139
+ /** Structured metadata riding alongside `chunk` for a richer UI — a search
140
+ * result ({title,url,snippet}) or a research phase record. */
141
+ item?: Record<string, unknown> | null;
142
+ /** Position within `total`, when the producer emits one item per step. */
143
+ index?: number | null;
144
+ total?: number | null;
145
+ /** Producers splat arbitrary extra keys (`generate_video` sends `status`,
146
+ * `preset`), so this payload is open-ended by design. */
147
+ [key: string]: unknown;
148
+ }
149
+ interface NestedLlmUsagePayload {
150
+ /** Which tool made the nested calls, e.g. "deep_research". */
151
+ source: string;
152
+ /** The parent tool call these nested calls belong to. */
153
+ callId: string;
154
+ inputTokens: number;
155
+ outputTokens: number;
156
+ cachedTokens: number;
157
+ cacheCreationTokens: number;
158
+ /** Number of nested LLM calls this event aggregates. */
159
+ llmCalls: number;
160
+ }
120
161
  interface UserUnavailablePayload {
121
162
  consecutiveTimeouts: number;
122
163
  toolName?: string | null;
@@ -206,6 +247,7 @@ declare const ChatEventType: {
206
247
  readonly ContextWarning: "context_warning";
207
248
  readonly MemoryRecall: "memory_recall";
208
249
  readonly MemoryUpdate: "memory_update";
250
+ readonly MemoryProviderError: "memory_provider_error";
209
251
  readonly DesktopStream: "desktop_stream";
210
252
  readonly AttachmentStaged: "attachment_staged";
211
253
  readonly WorkspaceReady: "workspace_ready";
@@ -214,6 +256,8 @@ declare const ChatEventType: {
214
256
  readonly ToolApprovalGranted: "tool_approval_granted";
215
257
  readonly ToolPermissionDenied: "tool_permission_denied";
216
258
  readonly ToolHarnessWarning: "tool_harness_warning";
259
+ readonly ToolProgress: "tool_progress";
260
+ readonly NestedLlmUsage: "nested_llm_usage";
217
261
  readonly UserUnavailable: "user_unavailable";
218
262
  readonly PromptSuggestion: "prompt_suggestion";
219
263
  readonly StateChanged: "state_changed";
@@ -493,6 +537,15 @@ type ChatEvent = {
493
537
  memoryId?: string | null;
494
538
  key?: string | null;
495
539
  namespace?: string | null;
540
+ } | {
541
+ type: "memory_provider_error";
542
+ /** The external memory provider that failed (registry slug, e.g. "mem0"). */
543
+ provider: string;
544
+ /** Which provider operation failed — "save" | "update" | "delete" | "get"
545
+ * | "recall" | "ingest" | "list_visible" | … */
546
+ op: string;
547
+ /** One-line "<ExceptionType>: <message>" detail, length-capped by the backend. */
548
+ error: string;
496
549
  } | {
497
550
  type: "desktop_stream";
498
551
  url: string;
@@ -537,6 +590,43 @@ type ChatEvent = {
537
590
  callId: string;
538
591
  message?: string | null;
539
592
  details?: Record<string, unknown> | null;
593
+ } | {
594
+ type: "tool_progress";
595
+ callId: string;
596
+ /** Known values: "stdout" | "stderr" | "progress" | "command". Typed as
597
+ * string for forward compat; the backend defaults to "progress". */
598
+ stream: string;
599
+ /** Live progress text to append; the backend newline-terminates chunks. */
600
+ chunk: string;
601
+ /** Emitting tool, e.g. "web_search" | "deep_research" | "generate_video".
602
+ * Every producer sends it; null only if a future one does not. The wire
603
+ * key is `tool`, but this layer chooses consumer-facing names rather than
604
+ * inheriting them, and every sibling tool event calls it `toolName`. */
605
+ toolName?: string | null;
606
+ /** Structured metadata riding alongside `chunk` for a richer UI — a search
607
+ * result ({title,url,snippet}) or a research phase record. Null when the
608
+ * producer sends none. */
609
+ item?: Record<string, unknown> | null;
610
+ /** Position within `total`, when the producer emits one item per step. */
611
+ index?: number | null;
612
+ total?: number | null;
613
+ /** The raw payload, verbatim. Producers send keys beyond the named ones —
614
+ * `generate_video` splats arbitrary `**extra` (`status`, `preset`) — so
615
+ * the named fields are a convenience, not the whole event. Read here for
616
+ * anything they do not cover. */
617
+ data: Record<string, unknown>;
618
+ } | {
619
+ type: "nested_llm_usage";
620
+ /** Which tool made the nested calls, e.g. "deep_research". */
621
+ source: string;
622
+ /** The parent tool call these nested calls belong to. */
623
+ callId: string;
624
+ inputTokens: number;
625
+ outputTokens: number;
626
+ cachedTokens: number;
627
+ cacheCreationTokens: number;
628
+ /** Number of nested LLM calls this event aggregates. */
629
+ llmCalls: number;
540
630
  } | {
541
631
  type: "user_unavailable";
542
632
  consecutiveTimeouts: number;
@@ -666,6 +756,43 @@ interface SkillInfo {
666
756
  description: string;
667
757
  isEnabled: boolean;
668
758
  }
759
+ /**
760
+ * A slash command the active agent offers — the system commands (`/new`,
761
+ * `/goal`, `/plan`, …) followed by its enabled skills, from
762
+ * `GET /v1/skills/commands`.
763
+ *
764
+ * The backend builds this list once and every surface reads it, so the web
765
+ * composer's "/" menu and the Telegram bot's command menu cannot drift.
766
+ */
767
+ interface SlashCommand {
768
+ /** What the user types after the slash, and what the backend parses. */
769
+ name: string;
770
+ /** Human-readable label for the menu row. May be empty. */
771
+ displayName: string;
772
+ /** One line describing what the command does. May be empty. */
773
+ description: string;
774
+ /**
775
+ * The argument shape a row shows after the name, e.g. `"[goal]"`. Empty
776
+ * when the command takes none — never undefined, so a renderer can
777
+ * concatenate it without a guard.
778
+ */
779
+ argsHint: string;
780
+ /**
781
+ * Which surfaces can run this command (`"web"`, `"telegram"`).
782
+ *
783
+ * Always populated, whatever surface was asked for — a scoped list has
784
+ * already filtered on it, so every row there names at least the surface
785
+ * requested. It carries information only for `"all"`, where rows that
786
+ * cannot run everywhere sit next to rows that can. Empty rather than
787
+ * undefined for the same reason as `argsHint`.
788
+ */
789
+ surfaces: string[];
790
+ }
791
+ /**
792
+ * Who will execute the commands {@link AstralformClient.listSkillCommands}
793
+ * returns. `"web"` is the server's default: what `POST /v1/jobs` runs itself.
794
+ */
795
+ type SlashCommandSurface = "web" | "telegram" | "all";
669
796
  interface JobCreateResponse {
670
797
  job_id: string;
671
798
  conversation_id: string;
@@ -1004,6 +1131,48 @@ interface ChatStreamEvent {
1004
1131
  event: string;
1005
1132
  data: string;
1006
1133
  }
1134
+ /**
1135
+ * A tool output the server declined to inline, with a handle to fetch it.
1136
+ *
1137
+ * Restore can ask for these with `toolOutputs: "stub"`. Only the `output` of a
1138
+ * `tool_use` final is ever replaced — name, arguments, status, duration and the
1139
+ * hoisted image previews all survive — so a stubbed tool call renders like a
1140
+ * resolved one until the reader opens it.
1141
+ */
1142
+ interface ToolOutputStub {
1143
+ __stub: "tool_output";
1144
+ call_id: string;
1145
+ /**
1146
+ * Size of the output this replaces, for a "load 240 KB" affordance.
1147
+ *
1148
+ * Optional because nothing in this SDK reads it, and the guard therefore
1149
+ * does not require it: rejecting an otherwise-valid stub over a display
1150
+ * field would drop it to "not a stub" and render the handle where the
1151
+ * output belongs — a worse outcome than a missing size label.
1152
+ */
1153
+ size_bytes?: number;
1154
+ /**
1155
+ * The job this call belongs to. **Hand it back to `getToolOutput`.**
1156
+ *
1157
+ * `/events?job_id=X` deliberately returns jobs that regeneration has
1158
+ * replaced — reading a superseded version is the whole purpose of that
1159
+ * parameter — while the fetch route excludes them unless scoped to a job. A
1160
+ * fetch that drops this therefore 404s on exactly the pills a
1161
+ * version-switched read is displaying. Absent only when the event carried no
1162
+ * job id, in which case the unscoped fetch is the correct one.
1163
+ */
1164
+ job_id?: string;
1165
+ }
1166
+ /**
1167
+ * Is this tool output a stub to fetch rather than the output itself?
1168
+ *
1169
+ * One obvious way to ask. Left to sniff `__stub` themselves, consumers get it
1170
+ * wrong in the direction that renders the stub object into the transcript
1171
+ * where the result belongs.
1172
+ */
1173
+ declare function isToolOutputStub(value: unknown): value is ToolOutputStub;
1174
+ /** How a restore asks for tool outputs. */
1175
+ type ToolOutputMode = "inline" | "stub";
1007
1176
  interface ConversationEvent {
1008
1177
  seq: number;
1009
1178
  event: string;
@@ -1148,6 +1317,32 @@ interface ConversationAsset {
1148
1317
  createdAt: string;
1149
1318
  }
1150
1319
 
1320
+ /**
1321
+ * One turn as the conversation's job list describes it.
1322
+ *
1323
+ * Deliberately WIDER than `restore-plan.ts`'s `RestoreJob`, which is the
1324
+ * narrow structural input `planRestore` needs. This is the wire shape, and
1325
+ * typing the page with the narrow one would drop `status` and `metrics` on
1326
+ * the floor — silently, since a narrower type is assignable.
1327
+ */
1328
+ interface ConversationJob {
1329
+ job_id: string;
1330
+ status: string;
1331
+ message_id?: string | null;
1332
+ metrics?: Record<string, unknown>;
1333
+ }
1334
+ /** One page of turns, plus where the next older page starts. */
1335
+ interface JobsPage {
1336
+ jobs: ConversationJob[];
1337
+ hasMore: boolean;
1338
+ nextBefore: string | null;
1339
+ }
1340
+ /** One page of messages, plus where the next older page starts. */
1341
+ interface MessagesPage {
1342
+ messages: Message[];
1343
+ hasMore: boolean;
1344
+ nextBeforeSeq: number | null;
1345
+ }
1151
1346
  declare class AstralformClient {
1152
1347
  private readonly baseURL;
1153
1348
  private readonly fetchFn;
@@ -1215,6 +1410,19 @@ declare class AstralformClient {
1215
1410
  private request;
1216
1411
  /** Fetch + status handling. Always called inside `withDeadline`. */
1217
1412
  private send;
1413
+ /**
1414
+ * A GET whose response HEADERS the caller needs, not only its body.
1415
+ *
1416
+ * Paging metadata rides on headers (`X-Has-More`, `X-Next-Before`) because
1417
+ * the bodies are bare lists that installed clients already parse as such.
1418
+ * Reading them needs the `Response`, which `get<T>` discards.
1419
+ *
1420
+ * Note the shape: the body is parsed INSIDE the raced callback, exactly as
1421
+ * `get`/`post`/`patch` do. See the comment above them — doing the parse
1422
+ * outside the deadline is the original hang, and this method is not an
1423
+ * exception to it.
1424
+ */
1425
+ private getWithHeaders;
1218
1426
  get<T>(path: string): Promise<T>;
1219
1427
  post<T>(path: string, body: unknown): Promise<T>;
1220
1428
  patch<T>(path: string, body: unknown): Promise<T>;
@@ -1237,6 +1445,38 @@ declare class AstralformClient {
1237
1445
  getConversations(limit?: number, offset?: number, options?: {
1238
1446
  repository?: string;
1239
1447
  }): Promise<Conversation[]>;
1448
+ /**
1449
+ * One page of a conversation's turns, newest-first window returned oldest-first.
1450
+ *
1451
+ * `hasMore` asks "are there OLDER turns beyond this page" — the only
1452
+ * direction a restore pages in, since it starts at the tail.
1453
+ *
1454
+ * **Degrades on an old backend.** A server without the cursor ignores the
1455
+ * unknown `limit` query param and returns the whole list, and its response
1456
+ * carries neither header — which reads here as one page with nothing older,
1457
+ * i.e. exactly today's behaviour. That is why absent headers must mean
1458
+ * `hasMore: false` rather than an error: the fallback has to be "everything
1459
+ * arrived", not "paging is broken".
1460
+ */
1461
+ getConversationJobsPage(conversationId: string, options?: {
1462
+ limit?: number;
1463
+ before?: string;
1464
+ }): Promise<JobsPage>;
1465
+ /**
1466
+ * One page of a conversation's messages, oldest-first within the page.
1467
+ *
1468
+ * Deliberately NOT folded into `getMessages`: that method is public surface
1469
+ * whose `Message[]` return type callers depend on, and the server keeps its
1470
+ * unbounded branch for exactly the same reason.
1471
+ *
1472
+ * Degrades like `getConversationJobsPage` — an old server ignores `limit`
1473
+ * and returns the whole branch with no headers, which reads as a single
1474
+ * complete page.
1475
+ */
1476
+ getMessagesPage(conversationId: string, options: {
1477
+ limit: number;
1478
+ beforeSeq?: number;
1479
+ }): Promise<MessagesPage>;
1240
1480
  getMessages(conversationId: string): Promise<Message[]>;
1241
1481
  /**
1242
1482
  * Replace the title the server generated from the conversation's first turn.
@@ -1264,7 +1504,45 @@ declare class AstralformClient {
1264
1504
  */
1265
1505
  getModels(): Promise<ModelOption[]>;
1266
1506
  getSkills(): Promise<SkillInfo[]>;
1267
- getConversationEvents(conversationId: string, jobId?: string): Promise<ConversationEvent[]>;
1507
+ /**
1508
+ * List the slash commands the active agent offers — the system commands
1509
+ * followed by its enabled skills. Backs the composer's "/" menu.
1510
+ *
1511
+ * @param surface Who will execute them. Omit for the server's default,
1512
+ * `"web"`: what `POST /v1/jobs` runs itself. `"telegram"` returns the
1513
+ * bot's commands under Telegram-valid names; `"all"` returns every
1514
+ * command, including those the other surfaces filter out — `surfaces` is
1515
+ * set on every row either way, and is what tells them apart here.
1516
+ *
1517
+ * The default surface is not sent as a query parameter. The server already
1518
+ * defaults to `web`, so omitting it keeps the request byte-identical to
1519
+ * what clients that call the raw path send today — same reasoning as
1520
+ * {@link getConversationEvents}'s `toolOutputs`.
1521
+ */
1522
+ listSkillCommands(surface?: SlashCommandSurface): Promise<SlashCommand[]>;
1523
+ getConversationEvents(conversationId: string, jobId?: string, options?: {
1524
+ toolOutputs?: ToolOutputMode;
1525
+ }): Promise<ConversationEvent[]>;
1526
+ /**
1527
+ * The full output behind a {@link ToolOutputStub}.
1528
+ *
1529
+ * The safe form: the stub carries its own `job_id`, so the scoping that a
1530
+ * version-switched read depends on cannot be dropped. See the id overload
1531
+ * below for what that scoping is and why omitting it 404s.
1532
+ */
1533
+ getToolOutput(conversationId: string, stub: ToolOutputStub): Promise<unknown>;
1534
+ /**
1535
+ * By ids. **Pass `jobId`** — this is the form that can get it wrong.
1536
+ *
1537
+ * `/events?job_id=X` deliberately returns jobs that regeneration has
1538
+ * replaced, since reading a superseded version is the whole purpose of that
1539
+ * parameter, while this route excludes them unless scoped to a job. Omit it
1540
+ * and the fetch 404s on exactly the pills a version-switched read is
1541
+ * displaying. Restore fetches events per job, so that is the normal path.
1542
+ *
1543
+ * Prefer the overload above, which takes the stub and cannot be got wrong.
1544
+ */
1545
+ getToolOutput(conversationId: string, callId: string, jobId?: string): Promise<unknown>;
1268
1546
  submitToolResult(request: ToolResultRequest): Promise<void>;
1269
1547
  submitToolApproval(request: ToolApprovalRequest): Promise<void>;
1270
1548
  /**
@@ -1472,6 +1750,19 @@ declare class ChatSession {
1472
1750
  * cheaper than adding a count query to every list call.
1473
1751
  */
1474
1752
  hasMoreConversations: boolean;
1753
+ /** True when the loaded window has OLDER turns behind it — the transcript's
1754
+ * analogue of `hasMoreConversations`, and what a scroll-to-top sentinel
1755
+ * gates on. False until a windowed load says otherwise, so a consumer that
1756
+ * never asks for a window never offers to page. */
1757
+ hasMoreTurns: boolean;
1758
+ /** Cursor for the next older MESSAGE page (`before_seq`), or null. */
1759
+ oldestMessageSeq: number | null;
1760
+ /** Cursor for the next older TURN page (`before`), or null. Set by the
1761
+ * restore that loaded the newest page; consumed by `loadEarlierTurns`. */
1762
+ oldestTurnCursor: string | null;
1763
+ /** Guards against a sentinel that re-fires while a page is still in flight
1764
+ * and stacks duplicate turns — the same guard `loadMoreConversations` uses. */
1765
+ isLoadingEarlierTurns: boolean;
1475
1766
  /** True while ``loadMoreConversations`` is in flight. */
1476
1767
  isLoadingConversations: boolean;
1477
1768
  messages: Message[];
@@ -1635,7 +1926,9 @@ declare class ChatSession {
1635
1926
  * Load conversation context (messages) without replaying events.
1636
1927
  * Used before reconnectToJob — SSE replay handles event replay.
1637
1928
  */
1638
- loadConversation(id: string): Promise<void>;
1929
+ loadConversation(id: string, options?: {
1930
+ limit?: number;
1931
+ }): Promise<void>;
1639
1932
  /**
1640
1933
  * Reconnect to a running job's SSE stream (e.g. after page reload).
1641
1934
  * Replays all events from the beginning and continues live.
@@ -1724,6 +2017,19 @@ declare class ChatSession {
1724
2017
  * tracking ids client-side cannot discover a row that moved into a region
1725
2018
  * already scanned.
1726
2019
  */
2020
+ /**
2021
+ * Put an older page of messages in FRONT of the loaded window.
2022
+ *
2023
+ * Pending optimistic sends stay at the tail. They are the newest thing in
2024
+ * the session by construction — a message this browser has posted and the
2025
+ * server has not confirmed — so sorting them in with a page of history
2026
+ * would move an unsent bubble into the middle of the transcript.
2027
+ *
2028
+ * Ids already present are dropped rather than duplicated: pages are cut on a
2029
+ * row sequence, but a turn landing mid-walk can still put one message in two
2030
+ * pages, and a doubled prompt is more visible than a missing one.
2031
+ */
2032
+ prependMessages(older: Message[]): void;
1727
2033
  loadMoreConversations(): Promise<Conversation[]>;
1728
2034
  /**
1729
2035
  * Rename a conversation, server first.
@@ -1844,6 +2150,42 @@ type StreamManagerEvent = {
1844
2150
  type: "stateChange";
1845
2151
  state: StreamState;
1846
2152
  conversationId: string | null;
2153
+ } | {
2154
+ /**
2155
+ * An older page of turns is about to be replayed.
2156
+ *
2157
+ * Everything between this and `historyPageEnd` belongs BEFORE what the
2158
+ * consumer already holds. The SDK says which turns and in what order;
2159
+ * where they go is the consumer's business, and deliberately so — block
2160
+ * placement is a rendering concern, and the one consumer that indexes
2161
+ * blocks by wire path cannot merge an older page into that index anyway,
2162
+ * because paths are allocated per job and collide across turns.
2163
+ */
2164
+ type: "historyPageStart";
2165
+ conversationId: string;
2166
+ position: "prepend";
2167
+ } | {
2168
+ type: "historyPageEnd";
2169
+ conversationId: string;
2170
+ position: "prepend";
2171
+ /** Whether anything older still remains after this page. */
2172
+ hasMore: boolean;
2173
+ /**
2174
+ * Did the whole page replay?
2175
+ *
2176
+ * `false` when a live turn took the view over mid-walk, or a turn
2177
+ * started. The conversation has NOT moved in either case, so the turns
2178
+ * already emitted are sitting in the live transcript and the id on this
2179
+ * event does not tell a consumer to drop them — while the cursor has
2180
+ * deliberately not advanced, so the very next page request replays the
2181
+ * same turns from the start.
2182
+ *
2183
+ * **A consumer must discard everything it buffered since
2184
+ * `historyPageStart` when this is `false`.** That is cheap by
2185
+ * construction: a page is replayed into an isolated view and merged only
2186
+ * at this event, precisely because block paths collide across turns.
2187
+ */
2188
+ complete: boolean;
1847
2189
  } | {
1848
2190
  type: "conversationChanged";
1849
2191
  conversationId: string | null;
@@ -1876,6 +2218,19 @@ type StreamManagerEvent = {
1876
2218
  type EventHandler = (event: StreamManagerEvent) => void;
1877
2219
  declare class StreamManager {
1878
2220
  private session;
2221
+ /** The oldest prompt drawn so far — where a prepended page's span ends. */
2222
+ private oldestDrawnMessageId;
2223
+ /**
2224
+ * Whether restore asks for tool outputs inline or as fetch handles.
2225
+ *
2226
+ * ONE setting, applied to both event waves — the newest page and every
2227
+ * `loadEarlierTurns` page. A consumer that got stubs only on scroll-up would
2228
+ * be worse off than one that got them nowhere: the pill would resolve itself
2229
+ * in the visible tail and need a fetch above the fold, for no stated reason.
2230
+ *
2231
+ * Defaults to inline, so this is inert until a consumer opts in.
2232
+ */
2233
+ private toolOutputs;
1879
2234
  private _state;
1880
2235
  private _activeConversationId;
1881
2236
  private _backgroundJobs;
@@ -1906,6 +2261,15 @@ declare class StreamManager {
1906
2261
  get activeConversationId(): string | null;
1907
2262
  get backgroundJobs(): ReadonlyMap<string, string>;
1908
2263
  on(handler: EventHandler): () => void;
2264
+ /**
2265
+ * Ask restore for stubbed tool outputs, resolved on demand.
2266
+ *
2267
+ * Only worth turning on by a consumer that can actually resolve a stub —
2268
+ * see `isToolOutputStub` and `client.getToolOutput`. One that cannot does
2269
+ * not render an empty result: it renders the stub OBJECT where the output
2270
+ * belongs, because that is what arrives in `final.output`.
2271
+ */
2272
+ setToolOutputMode(mode: ToolOutputMode): void;
1909
2273
  private emit;
1910
2274
  private setState;
1911
2275
  private attach;
@@ -2041,6 +2405,23 @@ declare class StreamManager {
2041
2405
  * has returned to where it started.
2042
2406
  */
2043
2407
  private turnStarted;
2408
+ /**
2409
+ * Re-issue the message load UNWINDOWED after a restore stopped before it
2410
+ * could write a turn cursor.
2411
+ *
2412
+ * The window is decided synchronously at restore entry, but "this restore
2413
+ * will page" is only settled once `replayHistory` clears its first abort
2414
+ * check. A send landing in between — nothing gates one during a restore —
2415
+ * stops the replay with the window already installed and the cursor never
2416
+ * written: a transcript truncated to one page that no pager can extend,
2417
+ * which is worse than the unbounded load this path did before windowing.
2418
+ * Reloading whole is that behaviour restored. Fire-and-forget: the load
2419
+ * token still makes a later switch win, and the pending-send reconciliation
2420
+ * inside `loadConversation` is what keeps the interrupting send's prompt.
2421
+ * Only called when the conversation has NOT moved — a superseding switch
2422
+ * announces and loads its own.
2423
+ */
2424
+ private reloadUnwindowed;
2044
2425
  /**
2045
2426
  * Replay a conversation's persisted history into the consumer's block view.
2046
2427
  *
@@ -2061,6 +2442,23 @@ declare class StreamManager {
2061
2442
  * what keeps a failed job list non-blocking exactly as it was when the fetch
2062
2443
  * lived here.
2063
2444
  */
2445
+ /**
2446
+ * Fetch and replay the next OLDER page of turns.
2447
+ *
2448
+ * The scroll-up half of tail-first restore: `restore` renders the newest
2449
+ * page and clears `restoring`, and this brings back what precedes it, on
2450
+ * demand. Full fidelity — the same per-job events wave the newest page uses,
2451
+ * just later — so a turn paged in here is byte-identical to the same turn
2452
+ * rendered live. That is the whole reason this defers the fetch rather than
2453
+ * rebuilding older turns from the message list, which persists no thinking
2454
+ * blocks and no custom events.
2455
+ *
2456
+ * Resolves to the number of turns emitted; 0 when there is nothing older,
2457
+ * a page is already in flight, or the view was taken over mid-fetch.
2458
+ */
2459
+ /** User prompts from a slice of the message window, in plan input shape. */
2460
+ private static userMessagesOf;
2461
+ loadEarlierTurns(conversationId: string): Promise<number>;
2064
2462
  private replayHistory;
2065
2463
  private setActiveConversation;
2066
2464
  }
@@ -2149,4 +2547,4 @@ declare function isEmbeddedResource(value: unknown): value is {
2149
2547
  */
2150
2548
  declare function parseEmbeddedResource(value: unknown): EmbeddedResource | null;
2151
2549
 
2152
- export { type ActiveJob, type AgentCapability, type AgentIdentity, type AgentInfo, type AgentStatus, type AssetCreatedPayload, type AstralformApiKeyConfig, AstralformClient, type AstralformConfig, AstralformError, type AstralformUserTokenConfig, type AttachmentStagedPayload, AuthenticationError, type AvailableRepositories, type AvailableRepository, type BlockDeltaPayload, CONVERSATION_PAGE_SIZE, type ChatEvent, ChatEventType, type ChatEventTypeValue, ChatSession, type ChatStorage, type ChatStreamEvent, type ChatStreamRequest, type CodeProject, ConnectionError, type ContextUpdatePayload, type ContextWarningPayload, type Conversation, type ConversationAsset, type ConversationEvent, type DesktopStreamPayload, type EffortRung, 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 NoteUpdatePayload, type PlanUpdatePayload, 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 ThinkingDescriptor, type ThinkingRungOption, 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, VOICE_POLISH_MODES, type VoiceConfig, type VoiceLLMMode, type VoicePolishEvent, type VoicePolishMode, type VoicePolishRequest, type VoiceTranscribeOptions, type VoiceTranscript, 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, isVoiceLLMMode, isVoicePolishMode, mapSseToChat, parseEmbeddedResource, parseVoicePolishFrame, replayEvents, streamJobSSE, translateDelta };
2550
+ export { type ActiveJob, type AgentCapability, type AgentIdentity, type AgentInfo, type AgentStatus, type AssetCreatedPayload, type AstralformApiKeyConfig, AstralformClient, type AstralformConfig, AstralformError, type AstralformUserTokenConfig, type AttachmentStagedPayload, AuthenticationError, type AvailableRepositories, type AvailableRepository, type BlockDeltaPayload, CONVERSATION_PAGE_SIZE, type ChatEvent, ChatEventType, type ChatEventTypeValue, ChatSession, type ChatStorage, type ChatStreamEvent, type ChatStreamRequest, type CodeProject, ConnectionError, type ContextUpdatePayload, type ContextWarningPayload, type Conversation, type ConversationAsset, type ConversationEvent, type DesktopStreamPayload, type EffortRung, type EmbeddedResource, type FeedbackRequest, type FeedbackResponse, InMemoryStorage, type JobCreateResponse, type JobStatus, type JobSummary, LLMNotConfiguredError, type MemoryProviderErrorPayload, type MemoryRecallPayload, type MemoryRecord, type MemoryUpdatePayload, type Message, type ModelChoiceOptions, type ModelOption, type MyToolGrantsPage, type NestedLlmUsagePayload, type NoteUpdatePayload, type PlanUpdatePayload, type PromptSuggestionPayload, type ProtocolAdapter, ProtocolRegistry, RateLimitError, type RateLimitErrorDetails, type RawSseEvent, type ReasoningEffort, type SendOptions, ServerError, type SkillInfo, type SlashCommand, type SlashCommandSurface, StreamAbortedError, type StreamJobSSEOptions, StreamManager, type StreamManagerEvent, type StreamState, type SubagentStartPayload, type SubagentStopPayload, type TaskStatus, type TeamAgentSummary, type TeamSummary, type ThinkingDescriptor, type ThinkingRungOption, 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 ToolOutputMode, type ToolOutputStub, type ToolPermissionDeniedPayload, type ToolProgressPayload, ToolRegistry, type ToolResult, type ToolResultRequest, type TurnUsage, type UIComponentsConfig, type UserUnavailablePayload, VOICE_POLISH_MODES, type VoiceConfig, type VoiceLLMMode, type VoicePolishEvent, type VoicePolishMode, type VoicePolishRequest, type VoiceTranscribeOptions, type VoiceTranscript, 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, isToolOutputStub, isVoiceLLMMode, isVoicePolishMode, mapSseToChat, parseEmbeddedResource, parseVoicePolishFrame, replayEvents, streamJobSSE, translateDelta };