@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/README.md +1 -0
- package/dist/index.cjs +411 -25
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +401 -3
- package/dist/index.d.ts +401 -3
- package/dist/index.js +410 -25
- package/dist/index.js.map +1 -1
- package/package.json +1 -1
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
|
-
|
|
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
|
|
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 };
|