@astralform/js 9.1.0 → 9.3.0

package/dist/index.d.cts

@@ -902,8 +902,10 @@ interface ThinkingDescriptor {
 }
 /**
  * The per-request model choice (client-side model selection). `provider` and
- * `model` are paired — send both or neither; when omitted, the server reuses the
- * conversation's last model or a connected-provider default.
+ * `model` are paired — send both or neither. Pass them on the first message of
+ * a new conversation: newer servers reject a new conversation that names no
+ * model, and every server accepts one that does. Omitted later, the server
+ * reuses the conversation's last model.
  */
 interface ModelChoiceOptions {
     provider?: string;
@@ -943,7 +945,9 @@ interface ChatStreamRequest {
     goal?: string;
     /**
      * Per-request model choice (client-side model selection), wire shape.
-     * `provider` and `model` are paired; omit to reuse the thread's last model.
+     * `provider` and `model` are paired. Pass them on a new conversation (newer
+     * servers reject one without); omit them mid-thread to reuse the thread's
+     * last model.
      */
     provider?: string;
     model?: string;
@@ -1082,7 +1086,11 @@ interface VoiceConfig {
     defaultMode: VoicePolishMode;
     /** In tap-to-talk mode, the pause that ends a recording. */
     silenceAutoStopSeconds: number;
-    /** Send the message as soon as the result is ready. */
+    /**
+     * @deprecated Always `false`. Auto-send was removed from the platform
+     * (2026-09-14); a dictation only fills the composer and the user sends it.
+     * Kept so existing code compiles; slated for removal in the next major.
+     */
     autoSend: boolean;
     maxRecordingSeconds: number;
     /**
@@ -1199,6 +1207,50 @@ interface ToolOutputStub {
 declare function isToolOutputStub(value: unknown): value is ToolOutputStub;
 /** How a restore asks for tool outputs. */
 type ToolOutputMode = "inline" | "stub";
+/**
+ * A tool's image preview the server declined to inline, with a handle to fetch it.
+ *
+ * Restore can ask for these with `toolImages: "stub"`. It replaces an entry of a
+ * `tool_use` final's `images` — and only that entry's `url`: `mime_type`,
+ * `width`, `height` and `bytes` survive, so a consumer can reserve the image's
+ * box before the bytes arrive and the transcript does not jump when they do.
+ * Resolve it with `client.getToolImage`.
+ *
+ * Previews are exempt from `toolOutputs: "stub"`, which is why this is its own
+ * opt-in: they are hoisted out of `output` precisely so a stubbed pill keeps its
+ * thumbnail, and on a picture-heavy conversation they were three quarters of
+ * the bytes a restore shipped before first render.
+ */
+interface ToolImageStub {
+    __stub: "tool_image";
+    call_id: string;
+    /** The entry's position in its call's `images` — what the fetch reads. */
+    index: number;
+    /**
+     * The job this call belongs to. The same rule as `ToolOutputStub.job_id`:
+     * a version-switched read returns superseded jobs the unscoped fetch cannot
+     * see. `getToolImage` takes the whole stub so it cannot be dropped.
+     */
+    job_id?: string;
+    mime_type?: string;
+    /** Pixel size of the preview, for reserving its box. */
+    width?: number;
+    height?: number;
+    /** Encoded size of the preview. */
+    bytes?: number;
+}
+/**
+ * Is this `images` entry a stub to fetch rather than a preview with a `url`?
+ *
+ * Checks every field the fetch is built from — `call_id` AND `index` — for the
+ * reason `isToolOutputStub` gives: narrowing on the marker alone hands a caller
+ * fields the type promises but the value lacks, and the next line puts them in
+ * a URL. The display fields are hints and are not required, so a stub missing
+ * its dimensions still resolves; it just cannot reserve its box.
+ */
+declare function isToolImageStub(value: unknown): value is ToolImageStub;
+/** How a restore asks for tool image previews. */
+type ToolImageMode = "inline" | "stub";
 interface ConversationEvent {
     seq: number;
     event: string;
@@ -1356,6 +1408,69 @@ interface ConversationJob {
     status: string;
     message_id?: string | null;
     metrics?: Record<string, unknown>;
+    /**
+     * The per-turn state a consumer rehydrates a restored transcript from —
+     * attachment chips, composer modes, goal linkage, the model the turn ran on.
+     *
+     * Every field below was ALREADY in this response and already fetched by the
+     * restore's own paged read. They were simply not TYPED, and a field the SDK
+     * does not surface is one a consumer cannot reach without re-requesting the
+     * endpoint itself — which is exactly what happened: the chat issued a second,
+     * UNBOUNDED `GET /jobs` on `restoreSettled`, a payload that grows with the
+     * transcript, landing before first paint (measured 409-959 ms on the #1052
+     * reference conversation). Widening the type is what lets that request be
+     * deleted rather than merely bounded, which keeps ONE page size and ONE
+     * cursor in the SDK instead of a second copy of both in every consumer.
+     *
+     * Optional throughout, because "the backend cannot say" is a real answer for
+     * most of them: a job older than the field, or a server that does not project
+     * it yet. `plan_mode`/`image_mode`/`video_mode` are three-valued for that
+     * reason — absent/null is NOT false. `llm_provider`/`llm_model` come as a
+     * pair or not at all.
+     */
+    created_at?: string | null;
+    completed_at?: string | null;
+    goal_id?: string | null;
+    goal_objective?: string | null;
+    plan_mode?: boolean | null;
+    image_mode?: boolean | null;
+    video_mode?: boolean | null;
+    llm_provider?: string | null;
+    llm_model?: string | null;
+    /**
+     * Files that rode along with this turn's user message, as display metadata.
+     *
+     * Present for every job that carried uploads WHATEVER its status — the files
+     * are stored at attach time, before the turn starts, so a stopped or failed
+     * turn still carried them and its bubble should still show them.
+     */
+    attachments?: ConversationJobAttachment[] | null;
+}
+/**
+ * One file that rode along with a turn's user message.
+ *
+ * Named rather than inlined into `ConversationJob.attachments`: a consumer
+ * rebuilding attachment chips writes a function over ONE of these, and an
+ * inline literal is nameable only by indexing back out of the parent
+ * (`NonNullable<ConversationJob["attachments"]>[number]`). Handing the rows
+ * over is pointless if the row's element type cannot be spelled.
+ *
+ * `asset_id` and `filename` are required while the rest of `ConversationJob`
+ * is optional, and that is not an oversight: the others are optional because
+ * the BACKEND may not project them (a job older than the field, a server that
+ * does not send it yet), whereas this whole object is built in one place and
+ * both fields are unconditionally populated from the asset row whenever an
+ * entry exists at all.
+ */
+interface ConversationJobAttachment {
+    asset_id: string;
+    filename: string;
+    media_type?: string | null;
+    size_bytes?: number | null;
+    /** Signed and expiring — the restored thumbnail. */
+    url?: string | null;
+    /** Permanent address, for keeping or linking. */
+    content_url?: string | null;
 }
 /** One page of turns, plus where the next older page starts. */
 interface JobsPage {
@@ -1450,6 +1565,8 @@ declare class AstralformClient {
      */
     private getWithHeaders;
     get<T>(path: string): Promise<T>;
+    /** A GET whose body is binary. Read inside the race, for the reason above. */
+    private getBlob;
     post<T>(path: string, body: unknown): Promise<T>;
     patch<T>(path: string, body: unknown): Promise<T>;
     private del;
@@ -1548,6 +1665,7 @@ declare class AstralformClient {
     listSkillCommands(surface?: SlashCommandSurface): Promise<SlashCommand[]>;
     getConversationEvents(conversationId: string, jobId?: string, options?: {
         toolOutputs?: ToolOutputMode;
+        toolImages?: ToolImageMode;
     }): Promise<ConversationEvent[]>;
     /**
      * The full output behind a {@link ToolOutputStub}.
@@ -1569,6 +1687,20 @@ declare class AstralformClient {
      * Prefer the overload above, which takes the stub and cannot be got wrong.
      */
     getToolOutput(conversationId: string, callId: string, jobId?: string): Promise<unknown>;
+    /**
+     * The image behind a {@link ToolImageStub}, as a `Blob` of the preview's bytes.
+     *
+     * Takes the stub itself and nothing else — the `job_id` scoping that
+     * `getToolOutput`'s id form warns about cannot be dropped from a value that
+     * carries it. There is deliberately no by-ids form.
+     *
+     * A `Blob` rather than a URL because the route is authenticated: an `<img
+     * src>` cannot send the bearer token, so a browser consumer turns this into
+     * an object URL (`URL.createObjectURL`) and revokes it when the image
+     * unmounts. The response is `private, immutable`, so a repeat fetch of the
+     * same preview is served by the HTTP cache.
+     */
+    getToolImage(conversationId: string, stub: ToolImageStub): Promise<Blob>;
     submitToolResult(request: ToolResultRequest): Promise<void>;
     submitToolApproval(request: ToolApprovalRequest): Promise<void>;
     /**
@@ -2138,6 +2270,20 @@ declare function streamJobSSE(options: StreamJobSSEOptions): AsyncGenerator<Chat
 
 type StreamState = "idle" | "streaming" | "restoring" | "detached";
 interface SendOptions extends ModelChoiceOptions {
+    /**
+     * Client tools to enable for THIS turn, overriding `session.enabledClientTools`
+     * for it alone. Omit to use that Set, which is the persistent default.
+     *
+     * Present here while `conversationId` — the session's other extra field — is
+     * deliberately absent, and the difference is worth stating so neither gets
+     * "tidied" to match the other. `send` overwrites `conversationId` on its
+     * forward below, because the manager owns the pointer, so accepting one would
+     * silently discard the caller's value. Nothing overwrites this: the spread
+     * carries it and `ChatSession.send` reads it as the override. It was missing
+     * only because it was never added — #55 fixed the same loss for `repository`
+     * in the forward direction and recorded that this one had gone the other way.
+     */
+    enabledClientTools?: string[];
     agentName?: string;
     uploadIds?: string[];
     planMode?: boolean;
@@ -2196,6 +2342,20 @@ type StreamManagerEvent = {
     position: "prepend";
     /** Whether anything older still remains after this page. */
     hasMore: boolean;
+    /**
+     * This page's turns, as the job list describes them — the rows this
+     * page was replayed FROM, handed over rather than re-fetched.
+     *
+     * A consumer rehydrating per-turn state (attachment chips, composer
+     * modes, goal runs, the turn's model) needs these for a prepended page
+     * exactly as it does for the first render, and has no cursor of its own
+     * to ask for them with. Empty when the page replayed nothing.
+     *
+     * Read this only when `complete` is `true`, for the same reason the
+     * buffered blocks are discarded otherwise: an incomplete page's cursor
+     * did not advance and the same turns replay again next request.
+     */
+    jobs: ConversationJob[];
     /**
      * Did the whole page replay?
      *
@@ -2240,6 +2400,18 @@ type StreamManagerEvent = {
      */
     type: "restoreSettled";
     conversationId: string;
+    /**
+     * The newest page's turns, as the job list describes them.
+     *
+     * The restore ALREADY fetched these — `jobList` asks for
+     * `RESTORE_TURN_PAGE_SIZE` of them, and gets that many from any server
+     * that honours the cursor (an older one ignores `limit` and answers with
+     * the whole list, the documented degrade). Handing them over is what lets
+     * a consumer rehydrate without issuing its OWN unbounded `GET /jobs`,
+     * which is unbounded against every server, not just an old one, and lands
+     * before first paint.
+     */
+    jobs: ConversationJob[];
 };
 type EventHandler = (event: StreamManagerEvent) => void;
 declare class StreamManager {
@@ -2257,6 +2429,12 @@ declare class StreamManager {
      * Defaults to inline, so this is inert until a consumer opts in.
      */
     private toolOutputs;
+    /**
+     * Whether restore asks for tool image previews inline or as fetch handles.
+     * Separate from `toolOutputs` because the server keeps them separate — see
+     * `ToolImageStub` — and on the same one-setting-both-waves rule.
+     */
+    private toolImages;
     private _state;
     private _activeConversationId;
     private _backgroundJobs;
@@ -2296,6 +2474,21 @@ declare class StreamManager {
      * belongs, because that is what arrives in `final.output`.
      */
     setToolOutputMode(mode: ToolOutputMode): void;
+    /**
+     * Ask restore for stubbed image previews, fetched on demand.
+     *
+     * The same caution as `setToolOutputMode`, sharper: a consumer that cannot
+     * resolve one (`isToolImageStub`, `client.getToolImage`) finds an `images`
+     * entry with no `url` and draws a broken image where the preview was.
+     */
+    setToolImageMode(mode: ToolImageMode): void;
+    /**
+     * The ONE options object both event waves fetch with — the newest page and
+     * every `loadEarlierTurns` page. Built in one place so an opt-in added here
+     * reaches both by construction: two literals at two call sites is how one
+     * wave would silently keep asking for inline payloads.
+     */
+    private get eventFetchOptions();
     private emit;
     private setState;
     private attach;
@@ -2573,4 +2766,4 @@ declare function isEmbeddedResource(value: unknown): value is {
  */
 declare function parseEmbeddedResource(value: unknown): EmbeddedResource | null;
 
-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 SendOptions$1 as SessionSendOptions, 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 ToolProgressPayload, ToolRegistry, type ToolResult, type ToolResultRequest, type ToolSource, 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 };
+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 ConversationJob, type ConversationJobAttachment, type DesktopStreamPayload, type EffortRung, type EmbeddedResource, type FeedbackRequest, type FeedbackResponse, InMemoryStorage, type JobCreateResponse, type JobStatus, type JobSummary, type JobsPage, LLMNotConfiguredError, type MemoryProviderErrorPayload, type MemoryRecallPayload, type MemoryRecord, type MemoryUpdatePayload, type Message, type MessagesPage, 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 SendOptions$1 as SessionSendOptions, 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 ToolImageMode, type ToolImageStub, type ToolOutputMode, type ToolOutputStub, type ToolProgressPayload, ToolRegistry, type ToolResult, type ToolResultRequest, type ToolSource, 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, isToolImageStub, isToolOutputStub, isVoiceLLMMode, isVoicePolishMode, mapSseToChat, parseEmbeddedResource, parseVoicePolishFrame, replayEvents, streamJobSSE, translateDelta };

package/dist/index.d.ts

@@ -902,8 +902,10 @@ interface ThinkingDescriptor {
 }
 /**
  * The per-request model choice (client-side model selection). `provider` and
- * `model` are paired — send both or neither; when omitted, the server reuses the
- * conversation's last model or a connected-provider default.
+ * `model` are paired — send both or neither. Pass them on the first message of
+ * a new conversation: newer servers reject a new conversation that names no
+ * model, and every server accepts one that does. Omitted later, the server
+ * reuses the conversation's last model.
  */
 interface ModelChoiceOptions {
     provider?: string;
@@ -943,7 +945,9 @@ interface ChatStreamRequest {
     goal?: string;
     /**
      * Per-request model choice (client-side model selection), wire shape.
-     * `provider` and `model` are paired; omit to reuse the thread's last model.
+     * `provider` and `model` are paired. Pass them on a new conversation (newer
+     * servers reject one without); omit them mid-thread to reuse the thread's
+     * last model.
      */
     provider?: string;
     model?: string;
@@ -1082,7 +1086,11 @@ interface VoiceConfig {
     defaultMode: VoicePolishMode;
     /** In tap-to-talk mode, the pause that ends a recording. */
     silenceAutoStopSeconds: number;
-    /** Send the message as soon as the result is ready. */
+    /**
+     * @deprecated Always `false`. Auto-send was removed from the platform
+     * (2026-09-14); a dictation only fills the composer and the user sends it.
+     * Kept so existing code compiles; slated for removal in the next major.
+     */
     autoSend: boolean;
     maxRecordingSeconds: number;
     /**
@@ -1199,6 +1207,50 @@ interface ToolOutputStub {
 declare function isToolOutputStub(value: unknown): value is ToolOutputStub;
 /** How a restore asks for tool outputs. */
 type ToolOutputMode = "inline" | "stub";
+/**
+ * A tool's image preview the server declined to inline, with a handle to fetch it.
+ *
+ * Restore can ask for these with `toolImages: "stub"`. It replaces an entry of a
+ * `tool_use` final's `images` — and only that entry's `url`: `mime_type`,
+ * `width`, `height` and `bytes` survive, so a consumer can reserve the image's
+ * box before the bytes arrive and the transcript does not jump when they do.
+ * Resolve it with `client.getToolImage`.
+ *
+ * Previews are exempt from `toolOutputs: "stub"`, which is why this is its own
+ * opt-in: they are hoisted out of `output` precisely so a stubbed pill keeps its
+ * thumbnail, and on a picture-heavy conversation they were three quarters of
+ * the bytes a restore shipped before first render.
+ */
+interface ToolImageStub {
+    __stub: "tool_image";
+    call_id: string;
+    /** The entry's position in its call's `images` — what the fetch reads. */
+    index: number;
+    /**
+     * The job this call belongs to. The same rule as `ToolOutputStub.job_id`:
+     * a version-switched read returns superseded jobs the unscoped fetch cannot
+     * see. `getToolImage` takes the whole stub so it cannot be dropped.
+     */
+    job_id?: string;
+    mime_type?: string;
+    /** Pixel size of the preview, for reserving its box. */
+    width?: number;
+    height?: number;
+    /** Encoded size of the preview. */
+    bytes?: number;
+}
+/**
+ * Is this `images` entry a stub to fetch rather than a preview with a `url`?
+ *
+ * Checks every field the fetch is built from — `call_id` AND `index` — for the
+ * reason `isToolOutputStub` gives: narrowing on the marker alone hands a caller
+ * fields the type promises but the value lacks, and the next line puts them in
+ * a URL. The display fields are hints and are not required, so a stub missing
+ * its dimensions still resolves; it just cannot reserve its box.
+ */
+declare function isToolImageStub(value: unknown): value is ToolImageStub;
+/** How a restore asks for tool image previews. */
+type ToolImageMode = "inline" | "stub";
 interface ConversationEvent {
     seq: number;
     event: string;
@@ -1356,6 +1408,69 @@ interface ConversationJob {
     status: string;
     message_id?: string | null;
     metrics?: Record<string, unknown>;
+    /**
+     * The per-turn state a consumer rehydrates a restored transcript from —
+     * attachment chips, composer modes, goal linkage, the model the turn ran on.
+     *
+     * Every field below was ALREADY in this response and already fetched by the
+     * restore's own paged read. They were simply not TYPED, and a field the SDK
+     * does not surface is one a consumer cannot reach without re-requesting the
+     * endpoint itself — which is exactly what happened: the chat issued a second,
+     * UNBOUNDED `GET /jobs` on `restoreSettled`, a payload that grows with the
+     * transcript, landing before first paint (measured 409-959 ms on the #1052
+     * reference conversation). Widening the type is what lets that request be
+     * deleted rather than merely bounded, which keeps ONE page size and ONE
+     * cursor in the SDK instead of a second copy of both in every consumer.
+     *
+     * Optional throughout, because "the backend cannot say" is a real answer for
+     * most of them: a job older than the field, or a server that does not project
+     * it yet. `plan_mode`/`image_mode`/`video_mode` are three-valued for that
+     * reason — absent/null is NOT false. `llm_provider`/`llm_model` come as a
+     * pair or not at all.
+     */
+    created_at?: string | null;
+    completed_at?: string | null;
+    goal_id?: string | null;
+    goal_objective?: string | null;
+    plan_mode?: boolean | null;
+    image_mode?: boolean | null;
+    video_mode?: boolean | null;
+    llm_provider?: string | null;
+    llm_model?: string | null;
+    /**
+     * Files that rode along with this turn's user message, as display metadata.
+     *
+     * Present for every job that carried uploads WHATEVER its status — the files
+     * are stored at attach time, before the turn starts, so a stopped or failed
+     * turn still carried them and its bubble should still show them.
+     */
+    attachments?: ConversationJobAttachment[] | null;
+}
+/**
+ * One file that rode along with a turn's user message.
+ *
+ * Named rather than inlined into `ConversationJob.attachments`: a consumer
+ * rebuilding attachment chips writes a function over ONE of these, and an
+ * inline literal is nameable only by indexing back out of the parent
+ * (`NonNullable<ConversationJob["attachments"]>[number]`). Handing the rows
+ * over is pointless if the row's element type cannot be spelled.
+ *
+ * `asset_id` and `filename` are required while the rest of `ConversationJob`
+ * is optional, and that is not an oversight: the others are optional because
+ * the BACKEND may not project them (a job older than the field, a server that
+ * does not send it yet), whereas this whole object is built in one place and
+ * both fields are unconditionally populated from the asset row whenever an
+ * entry exists at all.
+ */
+interface ConversationJobAttachment {
+    asset_id: string;
+    filename: string;
+    media_type?: string | null;
+    size_bytes?: number | null;
+    /** Signed and expiring — the restored thumbnail. */
+    url?: string | null;
+    /** Permanent address, for keeping or linking. */
+    content_url?: string | null;
 }
 /** One page of turns, plus where the next older page starts. */
 interface JobsPage {
@@ -1450,6 +1565,8 @@ declare class AstralformClient {
      */
     private getWithHeaders;
     get<T>(path: string): Promise<T>;
+    /** A GET whose body is binary. Read inside the race, for the reason above. */
+    private getBlob;
     post<T>(path: string, body: unknown): Promise<T>;
     patch<T>(path: string, body: unknown): Promise<T>;
     private del;
@@ -1548,6 +1665,7 @@ declare class AstralformClient {
     listSkillCommands(surface?: SlashCommandSurface): Promise<SlashCommand[]>;
     getConversationEvents(conversationId: string, jobId?: string, options?: {
         toolOutputs?: ToolOutputMode;
+        toolImages?: ToolImageMode;
     }): Promise<ConversationEvent[]>;
     /**
      * The full output behind a {@link ToolOutputStub}.
@@ -1569,6 +1687,20 @@ declare class AstralformClient {
      * Prefer the overload above, which takes the stub and cannot be got wrong.
      */
     getToolOutput(conversationId: string, callId: string, jobId?: string): Promise<unknown>;
+    /**
+     * The image behind a {@link ToolImageStub}, as a `Blob` of the preview's bytes.
+     *
+     * Takes the stub itself and nothing else — the `job_id` scoping that
+     * `getToolOutput`'s id form warns about cannot be dropped from a value that
+     * carries it. There is deliberately no by-ids form.
+     *
+     * A `Blob` rather than a URL because the route is authenticated: an `<img
+     * src>` cannot send the bearer token, so a browser consumer turns this into
+     * an object URL (`URL.createObjectURL`) and revokes it when the image
+     * unmounts. The response is `private, immutable`, so a repeat fetch of the
+     * same preview is served by the HTTP cache.
+     */
+    getToolImage(conversationId: string, stub: ToolImageStub): Promise<Blob>;
     submitToolResult(request: ToolResultRequest): Promise<void>;
     submitToolApproval(request: ToolApprovalRequest): Promise<void>;
     /**
@@ -2138,6 +2270,20 @@ declare function streamJobSSE(options: StreamJobSSEOptions): AsyncGenerator<Chat
 
 type StreamState = "idle" | "streaming" | "restoring" | "detached";
 interface SendOptions extends ModelChoiceOptions {
+    /**
+     * Client tools to enable for THIS turn, overriding `session.enabledClientTools`
+     * for it alone. Omit to use that Set, which is the persistent default.
+     *
+     * Present here while `conversationId` — the session's other extra field — is
+     * deliberately absent, and the difference is worth stating so neither gets
+     * "tidied" to match the other. `send` overwrites `conversationId` on its
+     * forward below, because the manager owns the pointer, so accepting one would
+     * silently discard the caller's value. Nothing overwrites this: the spread
+     * carries it and `ChatSession.send` reads it as the override. It was missing
+     * only because it was never added — #55 fixed the same loss for `repository`
+     * in the forward direction and recorded that this one had gone the other way.
+     */
+    enabledClientTools?: string[];
     agentName?: string;
     uploadIds?: string[];
     planMode?: boolean;
@@ -2196,6 +2342,20 @@ type StreamManagerEvent = {
     position: "prepend";
     /** Whether anything older still remains after this page. */
     hasMore: boolean;
+    /**
+     * This page's turns, as the job list describes them — the rows this
+     * page was replayed FROM, handed over rather than re-fetched.
+     *
+     * A consumer rehydrating per-turn state (attachment chips, composer
+     * modes, goal runs, the turn's model) needs these for a prepended page
+     * exactly as it does for the first render, and has no cursor of its own
+     * to ask for them with. Empty when the page replayed nothing.
+     *
+     * Read this only when `complete` is `true`, for the same reason the
+     * buffered blocks are discarded otherwise: an incomplete page's cursor
+     * did not advance and the same turns replay again next request.
+     */
+    jobs: ConversationJob[];
     /**
      * Did the whole page replay?
      *
@@ -2240,6 +2400,18 @@ type StreamManagerEvent = {
      */
     type: "restoreSettled";
     conversationId: string;
+    /**
+     * The newest page's turns, as the job list describes them.
+     *
+     * The restore ALREADY fetched these — `jobList` asks for
+     * `RESTORE_TURN_PAGE_SIZE` of them, and gets that many from any server
+     * that honours the cursor (an older one ignores `limit` and answers with
+     * the whole list, the documented degrade). Handing them over is what lets
+     * a consumer rehydrate without issuing its OWN unbounded `GET /jobs`,
+     * which is unbounded against every server, not just an old one, and lands
+     * before first paint.
+     */
+    jobs: ConversationJob[];
 };
 type EventHandler = (event: StreamManagerEvent) => void;
 declare class StreamManager {
@@ -2257,6 +2429,12 @@ declare class StreamManager {
      * Defaults to inline, so this is inert until a consumer opts in.
      */
     private toolOutputs;
+    /**
+     * Whether restore asks for tool image previews inline or as fetch handles.
+     * Separate from `toolOutputs` because the server keeps them separate — see
+     * `ToolImageStub` — and on the same one-setting-both-waves rule.
+     */
+    private toolImages;
     private _state;
     private _activeConversationId;
     private _backgroundJobs;
@@ -2296,6 +2474,21 @@ declare class StreamManager {
      * belongs, because that is what arrives in `final.output`.
      */
     setToolOutputMode(mode: ToolOutputMode): void;
+    /**
+     * Ask restore for stubbed image previews, fetched on demand.
+     *
+     * The same caution as `setToolOutputMode`, sharper: a consumer that cannot
+     * resolve one (`isToolImageStub`, `client.getToolImage`) finds an `images`
+     * entry with no `url` and draws a broken image where the preview was.
+     */
+    setToolImageMode(mode: ToolImageMode): void;
+    /**
+     * The ONE options object both event waves fetch with — the newest page and
+     * every `loadEarlierTurns` page. Built in one place so an opt-in added here
+     * reaches both by construction: two literals at two call sites is how one
+     * wave would silently keep asking for inline payloads.
+     */
+    private get eventFetchOptions();
     private emit;
     private setState;
     private attach;
@@ -2573,4 +2766,4 @@ declare function isEmbeddedResource(value: unknown): value is {
  */
 declare function parseEmbeddedResource(value: unknown): EmbeddedResource | null;
 
-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 SendOptions$1 as SessionSendOptions, 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 ToolProgressPayload, ToolRegistry, type ToolResult, type ToolResultRequest, type ToolSource, 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 };
+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 ConversationJob, type ConversationJobAttachment, type DesktopStreamPayload, type EffortRung, type EmbeddedResource, type FeedbackRequest, type FeedbackResponse, InMemoryStorage, type JobCreateResponse, type JobStatus, type JobSummary, type JobsPage, LLMNotConfiguredError, type MemoryProviderErrorPayload, type MemoryRecallPayload, type MemoryRecord, type MemoryUpdatePayload, type Message, type MessagesPage, 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 SendOptions$1 as SessionSendOptions, 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 ToolImageMode, type ToolImageStub, type ToolOutputMode, type ToolOutputStub, type ToolProgressPayload, ToolRegistry, type ToolResult, type ToolResultRequest, type ToolSource, 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, isToolImageStub, isToolOutputStub, isVoiceLLMMode, isVoicePolishMode, mapSseToChat, parseEmbeddedResource, parseVoicePolishFrame, replayEvents, streamJobSSE, translateDelta };