@astralform/js 7.1.1 → 7.3.0

package/dist/index.d.cts

@@ -822,7 +822,118 @@ interface StreamJobSSEOptions {
     headers: Record<string, string>;
     signal?: AbortSignal;
     fetchFn: typeof globalThis.fetch;
+    /** Request method; defaults to GET (the job event stream). */
+    method?: "GET" | "POST";
+    /** A JSON-serialised body for POST streams (the voice polish stream). */
+    body?: string;
 }
+/**
+ * The styles a transcript can be shaped into, as the server names them.
+ * `raw` never calls the model — the transcript is used as recognized.
+ */
+declare const VOICE_POLISH_MODES: readonly ["raw", "light", "structured", "formal"];
+type VoicePolishMode = (typeof VOICE_POLISH_MODES)[number];
+/** A mode that calls the polish model — every mode except `raw`. */
+type VoiceLLMMode = Exclude<VoicePolishMode, "raw">;
+/** Whether `value` is one of the four modes this SDK version knows. */
+declare function isVoicePolishMode(value: unknown): value is VoicePolishMode;
+/**
+ * Whether `mode` may be passed to `streamVoicePolish` — the check to make on
+ * `VoiceConfig.defaultMode`, which can be `raw`.
+ */
+declare function isVoiceLLMMode(mode: VoicePolishMode): mode is VoiceLLMMode;
+/**
+ * What a client needs to run the microphone for an agent, from
+ * `GET /v1/voice/config`. Deliberately carries no provider or model names.
+ */
+interface VoiceConfig {
+    enabled: boolean;
+    /**
+     * The styles the client may request, as the server names them. Kept as
+     * plain strings so a mode this SDK version does not know still reaches a
+     * picker; `isVoicePolishMode` narrows one.
+     */
+    modes: string[];
+    /**
+     * The style to use when the user has not picked one. Falls back to
+     * `structured` when the server names a mode this SDK does not know. Can be
+     * `raw`, which `streamVoicePolish` refuses — check it with `isVoiceLLMMode`
+     * (or compare against `"raw"`) before polishing.
+     */
+    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. */
+    autoSend: boolean;
+    maxRecordingSeconds: number;
+    /**
+     * Whether the configured recognizer emits live partial transcripts. Batch
+     * (Whisper-style) providers do not; they transcribe on stop.
+     */
+    supportsStreaming: boolean;
+    /**
+     * The project vocabulary, for display. The server applies it to every
+     * transcription and polish itself; `transcribeVoice({ hotwords })` and
+     * `VoicePolishRequest.hotwords` carry only the user's own words, which the
+     * server merges after these.
+     */
+    hotwords: string[];
+}
+/** One recording turned into text, from `POST /v1/voice/transcriptions`. */
+interface VoiceTranscript {
+    text: string;
+    language: string | null;
+    /** Length of the submitted audio, when the WAV header said so. */
+    durationMs: number | null;
+    /** Time the provider took. */
+    asrMs: number;
+}
+interface VoiceTranscribeOptions {
+    /** File name sent with the recording; defaults to `recording.wav`. */
+    filename?: string;
+    /**
+     * The user's own vocabulary — not the project's, which the server already
+     * holds and merges in first. Sent comma-separated, so a word cannot itself
+     * contain a comma.
+     */
+    hotwords?: string[];
+    /** ISO 639-1 hint; omit for auto-detection. */
+    language?: string;
+    /**
+     * Abort the upload. No client-side deadline applies to this call (a
+     * recording can run to `maxRecordingSeconds` and the upload with it), so
+     * this is the only way to give up on a stalled one; the promise rejects
+     * with the abort reason (the runtime's `AbortError`, or what was passed to
+     * `abort(reason)`).
+     */
+    signal?: AbortSignal;
+}
+interface VoicePolishRequest {
+    text: string;
+    /** One of the LLM modes; `raw` is refused by the server. */
+    mode: VoiceLLMMode;
+    /** The user's own vocabulary; the server merges it after the project's. */
+    hotwords?: string[];
+}
+/**
+ * One frame of the polish stream. `delta` text arrives in order; `done.text`
+ * is authoritative (the cleaned full output, which can differ from the
+ * concatenated deltas). On `error` keep the raw transcript; `partial` is what
+ * was streamed before the failure.
+ */
+type VoicePolishEvent = {
+    type: "delta";
+    text: string;
+} | {
+    type: "done";
+    text: string;
+    polishMs: number;
+} | {
+    type: "error";
+    reason: string;
+    partial: string;
+    detail?: string;
+};
 interface ChatStreamEvent {
     event: string;
     data: string;
@@ -1087,6 +1198,34 @@ declare class AstralformClient {
     revokeToolPermission(id: string): Promise<void>;
     private mapAsset;
     uploadFile(conversationId: string, file: Blob, filename?: string): Promise<ConversationAsset>;
+    /** The agent's voice-input defaults (`GET /v1/voice/config`). */
+    getVoiceConfig(): Promise<VoiceConfig>;
+    /**
+     * Transcribe one recording with the agent's configured speech-to-text
+     * provider (`POST /v1/voice/transcriptions`). 16 kHz mono 16-bit WAV is the
+     * reference format; anything the provider accepts works.
+     *
+     * Deliberately outside `withDeadline`: a recording can run to
+     * `VoiceConfig.maxRecordingSeconds`, so the 30 s default would cut real
+     * uploads off. Pass `options.signal` to give up on a stalled one; the
+     * promise then rejects with the abort reason — the runtime's `AbortError`,
+     * or whatever was passed to `abort(reason)`.
+     */
+    transcribeVoice(audio: Blob, options?: VoiceTranscribeOptions): Promise<VoiceTranscript>;
+    /**
+     * Stream the LLM rewrite of a transcript (`POST /v1/voice/polish`) as typed
+     * frames.
+     *
+     * Failures the server reports mid-stream arrive as an `error` frame, but
+     * the iteration itself can reject: aborting `signal` closes the connection
+     * (which cancels the model call upstream) and rejects with
+     * `StreamAbortedError`; a non-2xx open rejects with `AuthenticationError`,
+     * `RateLimitError` or `ServerError`; a network failure with
+     * `ConnectionError`. Wrap the `for await` accordingly.
+     */
+    streamVoicePolish(request: VoicePolishRequest, options?: {
+        signal?: AbortSignal;
+    }): AsyncGenerator<VoicePolishEvent>;
     listUploads(conversationId: string): Promise<ConversationAsset[]>;
     listOutputs(conversationId: string): Promise<ConversationAsset[]>;
     listTeams(): Promise<TeamSummary[]>;
@@ -1104,6 +1243,14 @@ declare class AstralformClient {
     getActiveJob(conversationId: string): Promise<ActiveJob>;
     listJobs(conversationId: string): Promise<JobSummary[]>;
 }
+/**
+ * Decode one SSE frame of `POST /v1/voice/polish`; null for frames the
+ * client does not act on (pings, unknown events).
+ */
+declare function parseVoicePolishFrame(frame: {
+    event: string;
+    data: string;
+}): VoicePolishEvent | null;
 
 /**
  * Minimal adapter contract. Frontends extend this with a `render()`
@@ -1532,7 +1679,8 @@ declare class StreamAbortedError extends AstralformError {
 declare function generateId(): string;
 
 /**
- * GET-based SSE stream for job events.
+ * SSE stream reader. GET for the job event stream (the default); POST with a
+ * JSON body for the voice polish stream. The frame parser is the same.
  */
 declare function streamJobSSE(options: StreamJobSSEOptions): AsyncGenerator<ChatStreamEvent>;
 
@@ -1614,6 +1762,13 @@ declare class StreamManager {
      * its awaits. This can.
      */
     private turnCounter;
+    /**
+     * True while a `resync` is between its probe and its restore. Visibility and
+     * focus listeners can both fire for one return, and two overlapping resyncs
+     * would each detach the other's stream mid-flight — the second call must
+     * find the flag set and leave the first to converge.
+     */
+    private _resyncing;
     constructor(session: ChatSession);
     get state(): StreamState;
     get activeConversationId(): string | null;
@@ -1645,6 +1800,38 @@ declare class StreamManager {
     switchTo(conversationId: string, opts?: {
         skipHistoryReplay?: boolean;
     }): Promise<void>;
+    /**
+     * Re-attach to whatever the server says is live for the ACTIVE conversation.
+     *
+     * The reconnect machinery inside ``consumeEventStream`` only runs while a
+     * stream is being consumed — and a page suspended in the background (locked
+     * phone, app switch, hidden tab) can outlive it: timers are throttled or
+     * suspended, so the stall watchdog may never fire while hidden; the
+     * reconnect budget (``SSE_MAX_RECONNECTS``) can burn out in fail-fast
+     * attempts; and a 401 from a rotated access token ends the loop outright as
+     * non-retryable. What is left is a manager that believes a turn is streaming
+     * (or has given up on one that is still running) with nothing attached — and
+     * no navigation will ever fix it, because ``switchTo`` early-returns on the
+     * conversation it is already on.
+     *
+     * So the consumer calls this when the user COMES BACK
+     * (``visibilitychange → visible``, window ``focus``). One ``getActiveJob``
+     * probe, then:
+     *
+     *  - attached to exactly the job the server calls live → healthy. The stall
+     *    watchdog owns zombie recovery from here, now that timers run again.
+     *    No-op.
+     *  - anything else — attached to a job the server no longer calls live,
+     *    attached to nothing while a job runs, or idle with a live job another
+     *    tab/device started — → detach and re-run ``restore``, the same path a
+     *    conversation reopen takes, with all of its supersession and takeover
+     *    guards inherited.
+     *
+     * Skipped while a restore is already in flight (it is converging on server
+     * truth by itself) and while another resync holds the flag — see
+     * ``_resyncing``.
+     */
+    resync(): Promise<void>;
     /**
      * Create a conversation and make it active.
      *
@@ -1816,4 +2003,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 BlockDeltaPayload, CONVERSATION_PAGE_SIZE, type ChatEvent, ChatEventType, type ChatEventTypeValue, ChatSession, type ChatStorage, type ChatStreamEvent, type ChatStreamRequest, ConnectionError, type ContextUpdatePayload, type ContextWarningPayload, type Conversation, type ConversationAsset, type ConversationEvent, type DesktopStreamPayload, type 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, type WireBlockDelta, type WireBlockDeltaPayload, type WireBlockKind, type WireBlockStart, type WireBlockStatus, type WireBlockStop, type WireCustomEvent, type WireErrorEvent, type WireEvent, type WireInputArgDelta, type WireInputDelta, type WireKeepalive, type WireMessageStart, type WireMessageStop, type WireOutputDelta, type WireRetryEvent, type WireSignatureDelta, type WireStallWarning, type WireStatusDelta, type WireStopReason, type WireTextDelta, type WireThinkingDelta, type WorkspaceReadyPayload, generateId, isEmbeddedResource, mapSseToChat, parseEmbeddedResource, replayEvents, streamJobSSE, translateDelta };
+export { type ActiveJob, type AgentCapability, type AgentIdentity, type AgentInfo, type AgentStatus, type AssetCreatedPayload, type AstralformApiKeyConfig, AstralformClient, type AstralformConfig, AstralformError, type AstralformUserTokenConfig, type AttachmentStagedPayload, AuthenticationError, type BlockDeltaPayload, CONVERSATION_PAGE_SIZE, type ChatEvent, ChatEventType, type ChatEventTypeValue, ChatSession, type ChatStorage, type ChatStreamEvent, type ChatStreamRequest, ConnectionError, type ContextUpdatePayload, type ContextWarningPayload, type Conversation, type ConversationAsset, type ConversationEvent, type DesktopStreamPayload, type 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 };

package/dist/index.d.ts

@@ -822,7 +822,118 @@ interface StreamJobSSEOptions {
     headers: Record<string, string>;
     signal?: AbortSignal;
     fetchFn: typeof globalThis.fetch;
+    /** Request method; defaults to GET (the job event stream). */
+    method?: "GET" | "POST";
+    /** A JSON-serialised body for POST streams (the voice polish stream). */
+    body?: string;
 }
+/**
+ * The styles a transcript can be shaped into, as the server names them.
+ * `raw` never calls the model — the transcript is used as recognized.
+ */
+declare const VOICE_POLISH_MODES: readonly ["raw", "light", "structured", "formal"];
+type VoicePolishMode = (typeof VOICE_POLISH_MODES)[number];
+/** A mode that calls the polish model — every mode except `raw`. */
+type VoiceLLMMode = Exclude<VoicePolishMode, "raw">;
+/** Whether `value` is one of the four modes this SDK version knows. */
+declare function isVoicePolishMode(value: unknown): value is VoicePolishMode;
+/**
+ * Whether `mode` may be passed to `streamVoicePolish` — the check to make on
+ * `VoiceConfig.defaultMode`, which can be `raw`.
+ */
+declare function isVoiceLLMMode(mode: VoicePolishMode): mode is VoiceLLMMode;
+/**
+ * What a client needs to run the microphone for an agent, from
+ * `GET /v1/voice/config`. Deliberately carries no provider or model names.
+ */
+interface VoiceConfig {
+    enabled: boolean;
+    /**
+     * The styles the client may request, as the server names them. Kept as
+     * plain strings so a mode this SDK version does not know still reaches a
+     * picker; `isVoicePolishMode` narrows one.
+     */
+    modes: string[];
+    /**
+     * The style to use when the user has not picked one. Falls back to
+     * `structured` when the server names a mode this SDK does not know. Can be
+     * `raw`, which `streamVoicePolish` refuses — check it with `isVoiceLLMMode`
+     * (or compare against `"raw"`) before polishing.
+     */
+    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. */
+    autoSend: boolean;
+    maxRecordingSeconds: number;
+    /**
+     * Whether the configured recognizer emits live partial transcripts. Batch
+     * (Whisper-style) providers do not; they transcribe on stop.
+     */
+    supportsStreaming: boolean;
+    /**
+     * The project vocabulary, for display. The server applies it to every
+     * transcription and polish itself; `transcribeVoice({ hotwords })` and
+     * `VoicePolishRequest.hotwords` carry only the user's own words, which the
+     * server merges after these.
+     */
+    hotwords: string[];
+}
+/** One recording turned into text, from `POST /v1/voice/transcriptions`. */
+interface VoiceTranscript {
+    text: string;
+    language: string | null;
+    /** Length of the submitted audio, when the WAV header said so. */
+    durationMs: number | null;
+    /** Time the provider took. */
+    asrMs: number;
+}
+interface VoiceTranscribeOptions {
+    /** File name sent with the recording; defaults to `recording.wav`. */
+    filename?: string;
+    /**
+     * The user's own vocabulary — not the project's, which the server already
+     * holds and merges in first. Sent comma-separated, so a word cannot itself
+     * contain a comma.
+     */
+    hotwords?: string[];
+    /** ISO 639-1 hint; omit for auto-detection. */
+    language?: string;
+    /**
+     * Abort the upload. No client-side deadline applies to this call (a
+     * recording can run to `maxRecordingSeconds` and the upload with it), so
+     * this is the only way to give up on a stalled one; the promise rejects
+     * with the abort reason (the runtime's `AbortError`, or what was passed to
+     * `abort(reason)`).
+     */
+    signal?: AbortSignal;
+}
+interface VoicePolishRequest {
+    text: string;
+    /** One of the LLM modes; `raw` is refused by the server. */
+    mode: VoiceLLMMode;
+    /** The user's own vocabulary; the server merges it after the project's. */
+    hotwords?: string[];
+}
+/**
+ * One frame of the polish stream. `delta` text arrives in order; `done.text`
+ * is authoritative (the cleaned full output, which can differ from the
+ * concatenated deltas). On `error` keep the raw transcript; `partial` is what
+ * was streamed before the failure.
+ */
+type VoicePolishEvent = {
+    type: "delta";
+    text: string;
+} | {
+    type: "done";
+    text: string;
+    polishMs: number;
+} | {
+    type: "error";
+    reason: string;
+    partial: string;
+    detail?: string;
+};
 interface ChatStreamEvent {
     event: string;
     data: string;
@@ -1087,6 +1198,34 @@ declare class AstralformClient {
     revokeToolPermission(id: string): Promise<void>;
     private mapAsset;
     uploadFile(conversationId: string, file: Blob, filename?: string): Promise<ConversationAsset>;
+    /** The agent's voice-input defaults (`GET /v1/voice/config`). */
+    getVoiceConfig(): Promise<VoiceConfig>;
+    /**
+     * Transcribe one recording with the agent's configured speech-to-text
+     * provider (`POST /v1/voice/transcriptions`). 16 kHz mono 16-bit WAV is the
+     * reference format; anything the provider accepts works.
+     *
+     * Deliberately outside `withDeadline`: a recording can run to
+     * `VoiceConfig.maxRecordingSeconds`, so the 30 s default would cut real
+     * uploads off. Pass `options.signal` to give up on a stalled one; the
+     * promise then rejects with the abort reason — the runtime's `AbortError`,
+     * or whatever was passed to `abort(reason)`.
+     */
+    transcribeVoice(audio: Blob, options?: VoiceTranscribeOptions): Promise<VoiceTranscript>;
+    /**
+     * Stream the LLM rewrite of a transcript (`POST /v1/voice/polish`) as typed
+     * frames.
+     *
+     * Failures the server reports mid-stream arrive as an `error` frame, but
+     * the iteration itself can reject: aborting `signal` closes the connection
+     * (which cancels the model call upstream) and rejects with
+     * `StreamAbortedError`; a non-2xx open rejects with `AuthenticationError`,
+     * `RateLimitError` or `ServerError`; a network failure with
+     * `ConnectionError`. Wrap the `for await` accordingly.
+     */
+    streamVoicePolish(request: VoicePolishRequest, options?: {
+        signal?: AbortSignal;
+    }): AsyncGenerator<VoicePolishEvent>;
     listUploads(conversationId: string): Promise<ConversationAsset[]>;
     listOutputs(conversationId: string): Promise<ConversationAsset[]>;
     listTeams(): Promise<TeamSummary[]>;
@@ -1104,6 +1243,14 @@ declare class AstralformClient {
     getActiveJob(conversationId: string): Promise<ActiveJob>;
     listJobs(conversationId: string): Promise<JobSummary[]>;
 }
+/**
+ * Decode one SSE frame of `POST /v1/voice/polish`; null for frames the
+ * client does not act on (pings, unknown events).
+ */
+declare function parseVoicePolishFrame(frame: {
+    event: string;
+    data: string;
+}): VoicePolishEvent | null;
 
 /**
  * Minimal adapter contract. Frontends extend this with a `render()`
@@ -1532,7 +1679,8 @@ declare class StreamAbortedError extends AstralformError {
 declare function generateId(): string;
 
 /**
- * GET-based SSE stream for job events.
+ * SSE stream reader. GET for the job event stream (the default); POST with a
+ * JSON body for the voice polish stream. The frame parser is the same.
  */
 declare function streamJobSSE(options: StreamJobSSEOptions): AsyncGenerator<ChatStreamEvent>;
 
@@ -1614,6 +1762,13 @@ declare class StreamManager {
      * its awaits. This can.
      */
     private turnCounter;
+    /**
+     * True while a `resync` is between its probe and its restore. Visibility and
+     * focus listeners can both fire for one return, and two overlapping resyncs
+     * would each detach the other's stream mid-flight — the second call must
+     * find the flag set and leave the first to converge.
+     */
+    private _resyncing;
     constructor(session: ChatSession);
     get state(): StreamState;
     get activeConversationId(): string | null;
@@ -1645,6 +1800,38 @@ declare class StreamManager {
     switchTo(conversationId: string, opts?: {
         skipHistoryReplay?: boolean;
     }): Promise<void>;
+    /**
+     * Re-attach to whatever the server says is live for the ACTIVE conversation.
+     *
+     * The reconnect machinery inside ``consumeEventStream`` only runs while a
+     * stream is being consumed — and a page suspended in the background (locked
+     * phone, app switch, hidden tab) can outlive it: timers are throttled or
+     * suspended, so the stall watchdog may never fire while hidden; the
+     * reconnect budget (``SSE_MAX_RECONNECTS``) can burn out in fail-fast
+     * attempts; and a 401 from a rotated access token ends the loop outright as
+     * non-retryable. What is left is a manager that believes a turn is streaming
+     * (or has given up on one that is still running) with nothing attached — and
+     * no navigation will ever fix it, because ``switchTo`` early-returns on the
+     * conversation it is already on.
+     *
+     * So the consumer calls this when the user COMES BACK
+     * (``visibilitychange → visible``, window ``focus``). One ``getActiveJob``
+     * probe, then:
+     *
+     *  - attached to exactly the job the server calls live → healthy. The stall
+     *    watchdog owns zombie recovery from here, now that timers run again.
+     *    No-op.
+     *  - anything else — attached to a job the server no longer calls live,
+     *    attached to nothing while a job runs, or idle with a live job another
+     *    tab/device started — → detach and re-run ``restore``, the same path a
+     *    conversation reopen takes, with all of its supersession and takeover
+     *    guards inherited.
+     *
+     * Skipped while a restore is already in flight (it is converging on server
+     * truth by itself) and while another resync holds the flag — see
+     * ``_resyncing``.
+     */
+    resync(): Promise<void>;
     /**
      * Create a conversation and make it active.
      *
@@ -1816,4 +2003,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 BlockDeltaPayload, CONVERSATION_PAGE_SIZE, type ChatEvent, ChatEventType, type ChatEventTypeValue, ChatSession, type ChatStorage, type ChatStreamEvent, type ChatStreamRequest, ConnectionError, type ContextUpdatePayload, type ContextWarningPayload, type Conversation, type ConversationAsset, type ConversationEvent, type DesktopStreamPayload, type 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, type WireBlockDelta, type WireBlockDeltaPayload, type WireBlockKind, type WireBlockStart, type WireBlockStatus, type WireBlockStop, type WireCustomEvent, type WireErrorEvent, type WireEvent, type WireInputArgDelta, type WireInputDelta, type WireKeepalive, type WireMessageStart, type WireMessageStop, type WireOutputDelta, type WireRetryEvent, type WireSignatureDelta, type WireStallWarning, type WireStatusDelta, type WireStopReason, type WireTextDelta, type WireThinkingDelta, type WorkspaceReadyPayload, generateId, isEmbeddedResource, mapSseToChat, parseEmbeddedResource, replayEvents, streamJobSSE, translateDelta };
+export { type ActiveJob, type AgentCapability, type AgentIdentity, type AgentInfo, type AgentStatus, type AssetCreatedPayload, type AstralformApiKeyConfig, AstralformClient, type AstralformConfig, AstralformError, type AstralformUserTokenConfig, type AttachmentStagedPayload, AuthenticationError, type BlockDeltaPayload, CONVERSATION_PAGE_SIZE, type ChatEvent, ChatEventType, type ChatEventTypeValue, ChatSession, type ChatStorage, type ChatStreamEvent, type ChatStreamRequest, ConnectionError, type ContextUpdatePayload, type ContextWarningPayload, type Conversation, type ConversationAsset, type ConversationEvent, type DesktopStreamPayload, type 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 };