@astralform/js 0.2.3 → 1.1.0

package/dist/index.d.cts

@@ -1,579 +1,513 @@
+interface AgentIdentity {
+    name: string;
+    displayName?: string | null;
+    avatarUrl?: string | null;
+    description?: string | null;
+}
+type TaskStatus = "pending" | "in_progress" | "completed" | "deleted";
+interface TodoItem {
+    id: number;
+    subject: string;
+    status: TaskStatus;
+    description?: string | null;
+    activeForm?: string | null;
+    owner?: string | null;
+    blockedBy?: number[] | null;
+    blocks?: number[] | null;
+    priority?: number | null;
+}
+interface TodoUpdatePayload {
+    todos: TodoItem[];
+}
+interface TitleGeneratedPayload {
+    title: string;
+}
+interface SubagentStartPayload {
+    agent: AgentIdentity;
+    taskCallId?: string | null;
+}
+interface SubagentStopPayload {
+    agent: AgentIdentity;
+    taskCallId?: string | null;
+}
+interface ContextWarningPayload {
+    /** Known values: "info" | "warning" | "critical". Typed as string for forward compat. */
+    severity: string;
+    utilizationPct: number;
+    remainingTokens: number;
+    windowTokens: number;
+    inputTokens: number;
+    message: string;
+}
+interface ContextUpdatePayload {
+    phase?: string | null;
+    updatedAt?: number | null;
+    context: Record<string, unknown>;
+}
 /**
- * BlockBuilder — pure rendering engine. Zero default behavior.
- *
- * Clients register handlers that map events to blocks.
- * Both live streaming and restore go through the same engine.
- *
- *   import { BlockBuilder, standardHandlers } from "@astralform/js";
- *   const builder = new BlockBuilder();
- *   builder.registerHandlers(standardHandlers);
+ * A single memory entry returned by ``memory_recall``. Backend may add
+ * fields over time, so the shape is intentionally open-ended.
  */
-
-interface UserBlock {
-    type: "user";
+interface MemoryRecord {
     id: string;
     content: string;
-    createdAt?: number;
+    [key: string]: unknown;
 }
-interface TextBlock {
-    type: "text";
-    id: string;
-    content: string;
-    isStreaming: boolean;
+interface MemoryRecallPayload {
+    memories: MemoryRecord[];
 }
-interface ThinkingBlock {
-    type: "thinking";
-    id: string;
-    content: string;
-    isActive: boolean;
-    durationMs?: number;
+interface MemoryUpdatePayload {
+    /** Known values: "created" | "updated" | "deleted". Typed as string for forward compat. */
+    action: string;
+    memoryId?: string | null;
+    key?: string | null;
+    namespace?: string | null;
 }
-interface AgentBlock {
-    type: "agent";
-    id: string;
-    agentName: string;
-    displayName?: string;
-    avatarUrl?: string;
+interface DesktopStreamPayload {
+    url: string;
+    sandboxId?: string | null;
 }
-interface SubagentBlock {
-    type: "subagent";
-    id: string;
-    agentName: string;
-    displayName: string;
-    toolCallId: string;
-    avatarUrl?: string;
-    description?: string;
-    content: string;
-    isActive: boolean;
+interface AttachmentStagedPayload {
+    attachmentId: string;
+    filename: string;
+    contentType?: string | null;
+    sizeBytes?: number | null;
 }
-interface ToolBlock {
-    type: "tool";
-    id: string;
-    callId: string;
-    toolName: string;
-    displayName?: string;
-    description?: string;
-    arguments?: Record<string, unknown>;
-    status: string;
-    iconUrl?: string;
-    toolCategory?: string;
-    sources?: {
-        title: string;
-        url: string;
-        snippet?: string;
-    }[];
-    durationMs?: number;
-    result?: string;
-}
-interface CapsuleBlock {
-    type: "capsule";
-    id: string;
-    callId: string;
-    toolName: string;
-    command?: string;
-    output: string;
-    durationMs?: number;
-    isActive: boolean;
+interface WorkspaceReadyPayload {
+    sandboxId: string;
+    workspacePath?: string | null;
 }
-interface AssetBlock {
-    type: "asset";
-    id: string;
+interface AssetCreatedPayload {
     assetId: string;
-    name: string;
-    url: string;
-    mediaType: string;
-    sizeBytes: number;
+    filename: string;
+    url?: string | null;
+    contentType?: string | null;
 }
-interface TodoBlock {
-    type: "todo";
-    id: string;
-    todos: {
-        content: string;
-        status: string;
-    }[];
+interface ToolApprovalRequestedPayload {
+    toolName: string;
+    callId: string;
+    arguments: Record<string, unknown>;
+    riskLevel?: string | null;
+    reason?: string | null;
 }
-interface EditorBlock {
-    type: "editor";
-    id: string;
+interface ToolApprovalGrantedPayload {
+    toolName: string;
     callId: string;
-    path: string;
-    language: string;
-    content: string;
-    isStreaming: boolean;
 }
-interface ErrorBlock {
-    type: "error";
-    id: string;
-    message: string;
+interface ToolPermissionDeniedPayload {
+    toolName: string;
+    callId: string;
+    reason?: string | null;
+    /** Known values: "hook" | "rule" | "user" | "timeout" | "circuit_breaker". */
+    deniedBy?: string | null;
 }
-interface DesktopStreamBlock {
-    type: "desktop_stream";
-    id: string;
-    url: string;
-    authKey: string;
-    sandboxId: string;
+interface ToolHarnessWarningPayload {
+    toolName: string;
+    callId: string;
+    message?: string | null;
+    details?: Record<string, unknown> | null;
 }
-interface AttachmentBlock {
-    type: "attachment";
-    id: string;
-    files: {
-        name: string;
-        path: string;
-        mediaType: string;
-        sizeBytes: number;
-    }[];
-}
-type Block = UserBlock | TextBlock | ThinkingBlock | AgentBlock | SubagentBlock | ToolBlock | CapsuleBlock | AssetBlock | TodoBlock | EditorBlock | DesktopStreamBlock | AttachmentBlock | ErrorBlock;
-type EventHandler$1 = (event: ChatEvent, builder: BlockBuilder) => void;
-declare class BlockBuilder {
-    private _blocks;
-    private _handlers;
-    private _onChange;
-    activeTextId: string | null;
-    activeThinkingId: string | null;
-    thinkingStartMs: number | null;
-    activeEditorId: string | null;
-    activeTodoId: string | null;
-    on(eventType: string, handler: EventHandler$1 | null): void;
-    registerHandlers(handlers: Record<string, EventHandler$1 | null>): void;
-    processEvent(event: ChatEvent): void;
-    getBlocks(): Block[];
-    reset(): void;
-    setOnChange(fn: (() => void) | null): void;
-    addBlock(block: Block): void;
-    updateBlock<T extends Block["type"]>(id: string, updater: (block: Extract<Block, {
-        type: T;
-    }>) => Extract<Block, {
-        type: T;
-    }>): void;
-    /** Update any block by id with a partial update (type-loose for handlers). */
-    patchBlock(id: string, patch: Partial<Block>): void;
-    findBlock(predicate: (b: Block) => boolean): Block | undefined;
-    nextId(): string;
-    private _notify;
+interface UserUnavailablePayload {
+    consecutiveTimeouts: number;
+    toolName?: string | null;
+}
+interface PromptSuggestionPayload {
+    suggestions: string[];
 }
 
-interface AstralformConfig {
-    apiKey: string;
+interface AstralformBaseConfig {
+    /** Override the default API origin. Defaults to https://api.astralform.ai. */
     baseURL?: string;
-    userId: string;
+    /** Supply a custom fetch (SSR, testing, custom interceptors). */
     fetch?: typeof globalThis.fetch;
 }
+interface AstralformApiKeyConfig extends AstralformBaseConfig {
+    /** Project API key (`sk_live_...` or `sk_test_...`). */
+    apiKey: string;
+    /**
+     * The customer's own identifier for the end user making this call.
+     * Sent as the `X-End-User-ID` header. Required in API-key mode.
+     */
+    userId: string;
+}
+interface AstralformUserTokenConfig extends AstralformBaseConfig {
+    /**
+     * OIDC access token issued by the Astralform Identity Provider.
+     * Expect this to be short-lived; use `client.updateAccessToken()` after
+     * refreshing to hot-swap without re-instantiating the client.
+     */
+    accessToken: string;
+    /**
+     * Active project context. Sent as the `X-Project-ID` header. The backend
+     * verifies the token's developer has access to this project on every
+     * request; switching projects is a local `updateProjectId()` call.
+     *
+     * Optional so a pre-pick client (right after login, before the user has
+     * chosen a team/project) can still call account-scoped discovery routes
+     * like `listTeams()` / `listProjects(teamId)`. Project-scoped calls
+     * (conversations, messages, chat) will error out until one is set.
+     */
+    projectId?: string;
+    /**
+     * Optional end-user override — lets a developer acting under a user
+     * token impersonate a downstream end-user identity for testing
+     * purposes. When set, sent alongside `X-Project-ID` as `X-End-User-ID`
+     * so memory, rate limits, and conversations scope to the specified
+     * end-user rather than the developer themselves.
+     *
+     * Use `client.updateEndUserId()` to rotate at runtime.
+     */
+    endUserId?: string;
+}
+type AstralformConfig = AstralformApiKeyConfig | AstralformUserTokenConfig;
 declare const ChatEventType: {
     readonly Connected: "connected";
-    readonly BlocksChanged: "blocks_changed";
+    readonly Disconnected: "disconnected";
+    readonly MessageStart: "message_start";
+    readonly MessageStop: "message_stop";
+    readonly BlockStart: "block_start";
+    readonly BlockDelta: "block_delta";
+    readonly BlockStop: "block_stop";
+    readonly Stall: "stall";
+    readonly Retry: "retry";
+    readonly Error: "error";
+    readonly Keepalive: "keepalive";
     readonly UserMessage: "user_message";
     readonly TitleGenerated: "title_generated";
-    readonly ModelInfo: "model_info";
-    readonly Chunk: "chunk";
-    readonly ToolCall: "tool_call";
-    readonly ToolExecuting: "tool_executing";
-    readonly ToolProgress: "tool_progress";
-    readonly ToolCompleted: "tool_completed";
-    readonly ToolEnd: "tool_end";
-    readonly AgentStart: "agent_start";
-    readonly AgentEnd: "agent_end";
-    readonly ThinkingDelta: "thinking_delta";
-    readonly ThinkingComplete: "thinking_complete";
-    readonly SubagentStart: "subagent_start";
-    readonly SubagentChunk: "subagent_chunk";
-    readonly SubagentUpdate: "subagent_update";
-    readonly SubagentEnd: "subagent_end";
-    readonly SubagentToolUse: "subagent_tool_use";
-    readonly CapsuleOutput: "capsule_output";
-    readonly CapsuleOutputChunk: "capsule_output_chunk";
-    readonly AssetCreated: "asset_created";
     readonly TodoUpdate: "todo_update";
-    readonly EditorContentStart: "editor_content_start";
-    readonly EditorContentDelta: "editor_content_delta";
-    readonly EditorContentEnd: "editor_content_end";
-    readonly Complete: "complete";
-    readonly Error: "error";
-    readonly Disconnected: "disconnected";
-    readonly Retry: "retry";
     readonly ContextUpdate: "context_update";
+    readonly SubagentStart: "subagent_start";
+    readonly SubagentStop: "subagent_stop";
+    readonly ContextWarning: "context_warning";
+    readonly MemoryRecall: "memory_recall";
+    readonly MemoryUpdate: "memory_update";
     readonly DesktopStream: "desktop_stream";
     readonly AttachmentStaged: "attachment_staged";
     readonly WorkspaceReady: "workspace_ready";
+    readonly AssetCreated: "asset_created";
+    readonly ToolApprovalRequested: "tool_approval_requested";
+    readonly ToolApprovalGranted: "tool_approval_granted";
+    readonly ToolPermissionDenied: "tool_permission_denied";
+    readonly ToolHarnessWarning: "tool_harness_warning";
+    readonly UserUnavailable: "user_unavailable";
+    readonly PromptSuggestion: "prompt_suggestion";
+    readonly StateChanged: "state_changed";
+    readonly Custom: "custom";
 };
-interface UserMessageEvent {
-    type: "user_message";
-    content: string;
-    created_at?: number;
-}
-interface TitleGeneratedEvent {
-    type: "title_generated";
-    title: string;
-}
-interface MessageStartEvent {
-    type: "message_start";
-    message_id: string;
-    conversation_id: string;
-    model_display_name?: string;
-    agent_name?: string;
-    agent_display_name?: string;
-}
-interface ContentBlockDeltaEvent {
-    type: "content_block_delta";
-    index: number;
-    delta: {
-        type: "text_delta";
-        text: string;
-    };
+type ChatEventTypeValue = (typeof ChatEventType)[keyof typeof ChatEventType];
+type WireBlockKind = "text" | "thinking" | "tool_use";
+type WireBlockStatus = "streaming" | "awaiting_client_result" | "ok" | "error" | "denied" | "cancelled";
+type WireStopReason = "end_turn" | "tool_use" | "max_tokens" | "context_overflow" | "error";
+interface WireTextDelta {
+    channel: "text";
+    text: string;
 }
-interface ToolUseStartEvent {
-    type: "tool_use_start";
-    index: number;
-    call_id: string;
-    tool: string;
-    display_name?: string;
-    description?: string;
-    arguments: Record<string, unknown>;
-    is_client_tool: boolean;
-    tool_category?: string;
-    icon_url?: string;
+interface WireThinkingDelta {
+    channel: "thinking";
+    text: string;
 }
-interface ToolUseEndEvent {
-    type: "tool_use_end";
-    call_id: string;
-    tool: string;
-    result?: string;
-    sources?: {
-        title: string;
-        url: string;
-        snippet?: string;
-    }[];
-    duration_ms?: number;
-}
-interface ToolExecutingEvent {
-    type: "tool_executing";
-    call_id: string;
-    tool: string;
+interface WireSignatureDelta {
+    channel: "signature";
+    signature: string;
 }
-interface ToolProgressEvent {
-    type: "tool_progress";
-    call_id: string;
-    tool: string;
-    index: number;
-    total: number;
-    item: {
-        title: string;
-        url: string;
-        snippet?: string;
-    };
+interface WireInputDelta {
+    channel: "input";
+    partial_json: string;
 }
-interface AgentStartEvent {
-    type: "agent_start";
-    agent_name: string;
-    agent_display_name?: string;
-    avatar_url?: string;
+interface WireInputArgDelta {
+    channel: "input_arg";
+    arg_name: string;
+    text: string;
 }
-interface AgentEndEvent {
-    type: "agent_end";
-    agent_name: string;
+interface WireOutputDelta {
+    channel: "output";
+    stream: "stdout" | "stderr" | "progress";
+    chunk: string;
 }
-interface SubagentStartEvent {
-    type: "subagent_start";
-    agent_name: string;
-    display_name: string;
-    tool_call_id: string;
-    avatar_url?: string;
-    description?: string;
+interface WireStatusDelta {
+    channel: "status";
+    status: "executing" | "awaiting_client_result" | "awaiting_approval" | "denied";
+    note?: string;
 }
-interface SubagentContentDeltaEvent {
-    type: "subagent_content_delta";
-    agent_name: string;
-    tool_call_id: string;
-    delta: {
-        type: "text_delta";
-        text: string;
-    };
+type WireBlockDeltaPayload = WireTextDelta | WireThinkingDelta | WireSignatureDelta | WireInputDelta | WireInputArgDelta | WireOutputDelta | WireStatusDelta;
+interface WireEnvelope {
+    seq: number;
+    ts: number;
+    job_id: string;
 }
-interface SubagentUpdateEvent {
-    type: "subagent_update";
-    agent_name: string;
-    display_name: string;
-    tool_call_id: string;
-}
-interface SubagentEndEvent {
-    type: "subagent_end";
-    agent_name: string;
-    display_name: string;
-    tool_call_id: string;
-}
-interface ThinkingDeltaEvent {
-    type: "thinking_delta";
-    delta: {
-        type: "thinking";
-        text: string;
+interface WireMessageStart extends WireEnvelope {
+    type: "message_start";
+    turn_id: string;
+    model: string;
+    agent_name?: string | null;
+    agent_display_name?: string | null;
+    agent_avatar_url?: string | null;
+}
+interface WireBlockStart extends WireEnvelope {
+    type: "block_start";
+    turn_id: string;
+    path: number[];
+    parent_path?: number[] | null;
+    kind: WireBlockKind;
+    metadata: Record<string, unknown>;
+}
+interface WireBlockDelta extends WireEnvelope {
+    type: "block_delta";
+    turn_id: string;
+    path: number[];
+    delta: WireBlockDeltaPayload;
+}
+interface WireBlockStop extends WireEnvelope {
+    type: "block_stop";
+    turn_id: string;
+    path: number[];
+    status: WireBlockStatus;
+    final: Record<string, unknown>;
+}
+interface WireMessageStop extends WireEnvelope {
+    type: "message_stop";
+    turn_id: string;
+    stop_reason: WireStopReason;
+    usage: {
+        input_tokens?: number;
+        output_tokens?: number;
+        cached_tokens?: number;
     };
+    ttfb_ms?: number | null;
+    total_ms: number;
+    stall_count: number;
 }
-interface ThinkingCompleteEvent {
-    type: "thinking_complete";
-}
-interface CapsuleOutputEvent {
-    type: "capsule_output";
-    tool_name: string;
-    agent_name: string;
-    command?: string;
-    output: string;
-    duration_ms?: number;
-    call_id?: string;
-}
-interface CapsuleOutputChunkEvent {
-    type: "capsule_output_chunk";
-    call_id: string;
-    stream: "stdout" | "stderr";
-    chunk: string;
+interface WireStallWarning extends WireEnvelope {
+    type: "stall";
+    since_last_event_ms: number;
+    stall_count: number;
 }
-interface TodoUpdateEvent {
-    type: "todo_update";
-    todos: TodoItem[];
-}
-interface MessageStopEvent {
-    type: "message_stop";
-    stop_reason: "end_turn" | "tool_use";
-    title?: string;
-    metrics?: Record<string, unknown>;
-    job_id?: string;
+interface WireRetryEvent extends WireEnvelope {
+    type: "retry";
+    attempt: number;
+    reason: string;
+    backoff_ms: number;
+    strategy?: string | null;
+    max_attempts?: number | null;
+    context_recovery?: Record<string, unknown> | null;
 }
-interface SSEErrorEvent {
+interface WireErrorEvent extends WireEnvelope {
     type: "error";
     code: string;
     message: string;
-}
-interface SubagentToolUseEvent {
-    type: "subagent_tool_use";
-    agent_name: string;
-    tool: string;
-    tool_call_id: string;
-    result?: string;
-}
-interface AssetCreatedEvent {
-    type: "asset_created";
-    asset_id: string;
+    block_path?: number[] | null;
+    retry_after?: number;
+    retry_after_sec?: number;
+    reset_at?: number | string;
+    scope?: string;
+    policy_id?: string;
+    limit?: number;
+    remaining?: number;
+    request_id?: string;
+}
+interface WireKeepalive extends WireEnvelope {
+    type: "keepalive";
+    since_last_event_ms: number;
+}
+interface WireCustomEvent extends WireEnvelope {
+    type: "custom";
     name: string;
-    url: string;
-    media_type: string;
-    size_bytes: number;
-}
-interface EditorContentStartEvent {
-    type: "editor_content_start";
-    call_id: string;
-    path: string;
-    language: string;
-}
-interface EditorContentDeltaEvent {
-    type: "editor_content_delta";
-    call_id: string;
-    path: string;
-    delta: string;
-}
-interface EditorContentEndEvent {
-    type: "editor_content_end";
-    call_id: string;
-}
-interface RetryEvent {
-    type: "retry";
-    attempt: number;
-    max_attempts: number;
-    delay_seconds: number;
-}
-interface ContextUpdateEvent {
-    type: "context_update";
-    context: Record<string, unknown>;
-    phase?: string;
-    updated_at?: number;
-}
-interface DesktopStreamEvent {
-    type: "desktop_stream";
-    url: string;
-    auth_key: string;
-    sandbox_id: string;
+    data: Record<string, unknown>;
 }
-interface AttachmentStagedEvent {
-    type: "attachment_staged";
-    files: {
-        name: string;
-        path: string;
-        media_type: string;
-        size_bytes: number;
-    }[];
-}
-interface WorkspaceReadyEvent {
-    type: "workspace_ready";
-    conversation_id: string;
-    sandbox_id: string;
+type WireEvent = WireMessageStart | WireBlockStart | WireBlockDelta | WireBlockStop | WireMessageStop | WireStallWarning | WireRetryEvent | WireErrorEvent | WireKeepalive | WireCustomEvent;
+interface TurnUsage {
+    inputTokens: number;
+    outputTokens: number;
+    cachedTokens: number;
 }
-type SSEEvent = MessageStartEvent | UserMessageEvent | TitleGeneratedEvent | ContentBlockDeltaEvent | ToolUseStartEvent | ToolUseEndEvent | ToolExecutingEvent | ToolProgressEvent | AgentStartEvent | AgentEndEvent | SubagentStartEvent | SubagentContentDeltaEvent | SubagentUpdateEvent | SubagentEndEvent | SubagentToolUseEvent | ThinkingDeltaEvent | ThinkingCompleteEvent | CapsuleOutputEvent | CapsuleOutputChunkEvent | TodoUpdateEvent | MessageStopEvent | AssetCreatedEvent | EditorContentStartEvent | EditorContentDeltaEvent | EditorContentEndEvent | RetryEvent | ContextUpdateEvent | DesktopStreamEvent | AttachmentStagedEvent | WorkspaceReadyEvent | SSEErrorEvent;
-type ChatEvent = {
-    type: "connected";
-} | {
-    type: "user_message";
-    content: string;
-    createdAt?: number;
-} | {
-    type: "title_generated";
-    title: string;
+type BlockDeltaPayload = {
+    channel: "text";
+    text: string;
 } | {
-    type: "chunk";
+    channel: "thinking";
     text: string;
 } | {
-    type: "tool_call";
-    request: ToolCallRequest;
+    channel: "signature";
+    signature: string;
 } | {
-    type: "tool_executing";
-    name: string;
-    call_id?: string;
+    channel: "input";
+    partialJson: string;
 } | {
-    type: "tool_completed";
-    name: string;
-    result: string;
+    channel: "inputArg";
+    argName: string;
+    text: string;
 } | {
-    type: "tool_progress";
-    callId: string;
-    tool: string;
-    index: number;
-    total: number;
-    item: {
-        title: string;
-        url: string;
-        snippet?: string;
-    };
+    channel: "output";
+    stream: "stdout" | "stderr" | "progress";
+    chunk: string;
 } | {
-    type: "tool_end";
-    callId: string;
-    toolName: string;
-    result?: string;
-    sources?: {
-        title: string;
-        url: string;
-        snippet?: string;
-    }[];
-    durationMs?: number;
-} | {
-    type: "agent_start";
-    agentName: string;
-    agentDisplayName?: string;
-    avatarUrl?: string;
+    channel: "status";
+    status: "executing" | "awaiting_client_result" | "awaiting_approval" | "denied";
+    note?: string;
+};
+type ChatEvent = {
+    type: "connected";
 } | {
-    type: "agent_end";
-    agentName: string;
+    type: "disconnected";
 } | {
-    type: "thinking_delta";
-    text: string;
+    type: "message_start";
+    turnId: string;
+    model: string;
+    agentName?: string | null;
+    agentDisplayName?: string | null;
+    agentAvatarUrl?: string | null;
 } | {
-    type: "thinking_complete";
+    type: "message_stop";
+    turnId: string;
+    jobId: string;
+    stopReason: WireStopReason;
+    usage: TurnUsage;
+    ttfbMs?: number | null;
+    totalMs: number;
+    stallCount: number;
 } | {
-    type: "subagent_start";
-    agentName: string;
-    displayName: string;
-    toolCallId: string;
-    avatarUrl?: string;
-    description?: string;
+    type: "block_start";
+    turnId: string;
+    path: number[];
+    parentPath?: number[] | null;
+    kind: WireBlockKind;
+    metadata: Record<string, unknown>;
 } | {
-    type: "subagent_chunk";
-    agentName: string;
-    toolCallId: string;
-    text: string;
+    type: "block_delta";
+    turnId: string;
+    path: number[];
+    delta: BlockDeltaPayload;
 } | {
-    type: "subagent_update";
-    agentName: string;
-    displayName: string;
-    toolCallId: string;
+    type: "block_stop";
+    turnId: string;
+    path: number[];
+    status: WireBlockStatus;
+    final: Record<string, unknown>;
 } | {
-    type: "subagent_end";
-    agentName: string;
-    displayName: string;
-    toolCallId: string;
+    type: "stall";
+    sinceLastEventMs: number;
+    stallCount: number;
 } | {
-    type: "capsule_output";
-    toolName: string;
-    agentName: string;
-    command?: string;
-    output: string;
-    durationMs?: number;
-    callId?: string;
+    type: "retry";
+    attempt: number;
+    reason: string;
+    backoffMs: number;
+    strategy?: string | null;
+    maxAttempts?: number | null;
+    contextRecovery?: Record<string, unknown> | null;
 } | {
-    type: "capsule_output_chunk";
-    callId: string;
-    stream: "stdout" | "stderr";
-    chunk: string;
+    type: "error";
+    code: string;
+    message: string;
+    blockPath: number[] | null;
 } | {
-    type: "todo_update";
-    todos: TodoItem[];
+    type: "keepalive";
+    sinceLastEventMs: number;
 } | {
-    type: "complete";
+    type: "user_message";
     content: string;
-    conversationId: string;
-    messageId: string;
-    title?: string;
-    metrics?: Record<string, unknown>;
-    job_id?: string;
-} | {
-    type: "subagent_tool_use";
-    agentName: string;
-    toolName: string;
-    toolCallId: string;
-    result?: string;
+    createdAt?: number;
 } | {
-    type: "asset_created";
-    assetId: string;
-    name: string;
-    url: string;
-    mediaType: string;
-    sizeBytes: number;
+    type: "title_generated";
+    title: string;
 } | {
-    type: "retry";
-    attempt: number;
-    maxAttempts: number;
-    delaySeconds: number;
+    type: "todo_update";
+    todos: TodoItem[];
 } | {
     type: "context_update";
     context: Record<string, unknown>;
-    phase?: string;
-    updatedAt?: number;
+    phase?: string | null;
+    updatedAt?: number | null;
 } | {
-    type: "editor_content_start";
-    callId: string;
-    path: string;
-    language: string;
+    type: "subagent_start";
+    agent: AgentIdentity;
+    taskCallId?: string | null;
 } | {
-    type: "editor_content_delta";
-    callId: string;
-    path: string;
-    delta: string;
+    type: "subagent_stop";
+    agent: AgentIdentity;
+    taskCallId?: string | null;
 } | {
-    type: "editor_content_end";
-    callId: string;
+    type: "context_warning";
+    /** Known values: "info" | "warning" | "critical". Typed as string for forward compat. */
+    severity: string;
+    utilizationPct: number;
+    remainingTokens: number;
+    windowTokens: number;
+    inputTokens: number;
+    message: string;
+} | {
+    type: "memory_recall";
+    memories: MemoryRecord[];
+} | {
+    type: "memory_update";
+    /** Known values: "created" | "updated" | "deleted". */
+    action: string;
+    memoryId?: string | null;
+    key?: string | null;
+    namespace?: string | null;
 } | {
     type: "desktop_stream";
     url: string;
-    authKey: string;
-    sandboxId: string;
+    sandboxId?: string | null;
 } | {
     type: "attachment_staged";
-    files: {
-        name: string;
-        path: string;
-        mediaType: string;
-        sizeBytes: number;
-    }[];
+    attachmentId: string;
+    filename: string;
+    contentType?: string | null;
+    sizeBytes?: number | null;
 } | {
     type: "workspace_ready";
-    conversationId: string;
     sandboxId: string;
+    workspacePath?: string | null;
 } | {
-    type: "model_info";
-    name: string;
+    type: "asset_created";
+    assetId: string;
+    filename: string;
+    url?: string | null;
+    contentType?: string | null;
 } | {
-    type: "blocks_changed";
-    blocks: Block[];
+    type: "tool_approval_requested";
+    toolName: string;
+    callId: string;
+    arguments: Record<string, unknown>;
+    riskLevel?: string | null;
+    reason?: string | null;
 } | {
-    type: "error";
-    error: Error;
+    type: "tool_approval_granted";
+    toolName: string;
+    callId: string;
 } | {
-    type: "disconnected";
+    type: "tool_permission_denied";
+    toolName: string;
+    callId: string;
+    reason?: string | null;
+    /** Known values: "hook" | "rule" | "user" | "timeout" | "circuit_breaker". */
+    deniedBy?: string | null;
+} | {
+    type: "tool_harness_warning";
+    toolName: string;
+    callId: string;
+    message?: string | null;
+    details?: Record<string, unknown> | null;
+} | {
+    type: "user_unavailable";
+    consecutiveTimeouts: number;
+    toolName?: string | null;
+} | {
+    type: "prompt_suggestion";
+    suggestions: string[];
+} | {
+    type: "state_changed";
+    /**
+     * Job lifecycle state. Known values from the backend today include
+     * "queued" | "running" | "waiting_for_tool" | "completed" | "failed".
+     * Typed as string for forward compat.
+     */
+    state: string;
+} | {
+    type: "custom";
+    name: string;
+    data: Record<string, unknown>;
 };
 interface Conversation {
     id: string;
@@ -592,12 +526,20 @@ interface Message {
     createdAt: string;
     toolCalls?: ToolCallRequest[];
 }
+interface UIComponentsConfig {
+    enabled: boolean;
+    /** Protocol slug (e.g. "a2ui"). Null when disabled. */
+    protocol: string | null;
+    /** MIME type to match against embedded resources (e.g. "application/json+a2ui"). */
+    mimeType: string | null;
+}
 interface ProjectStatus {
     isReady: boolean;
     llmConfigured: boolean;
     llmProvider?: string;
     llmModel?: string;
     message: string;
+    uiComponents: UIComponentsConfig;
 }
 interface AgentInfo {
     name: string;
@@ -607,52 +549,67 @@ interface AgentInfo {
     isEnabled: boolean;
     avatarUrl?: string;
 }
+interface TeamSummary {
+    id: string;
+    name: string;
+    slug: string;
+    isDefault: boolean;
+    /** Caller's role in this team (e.g. "owner", "admin", "member"). */
+    role: string;
+}
+interface ProjectSummary {
+    id: string;
+    name: string;
+    teamId: string;
+    createdAt: string;
+    updatedAt: string;
+}
 interface SkillInfo {
     name: string;
     displayName: string;
     description: string;
     isEnabled: boolean;
 }
-interface SubagentState {
-    agentName: string;
-    displayName: string;
-    avatarUrl?: string;
-    description?: string;
-    content: string;
-    isActive: boolean;
-}
-interface ToolState {
-    toolName: string;
-    displayName?: string;
-    description?: string;
-    arguments?: Record<string, unknown>;
-    callId: string;
-    status: "calling" | "executing" | "completed";
-    isClientTool: boolean;
-}
-interface CapsuleOutput {
-    toolName: string;
-    agentName: string;
-    command?: string;
-    output: string;
-    durationMs?: number;
-    callId?: string;
-}
-interface Source {
-    title: string;
-    url: string;
-}
-interface TodoItem {
-    content: string;
-    status: "pending" | "in_progress" | "completed";
-    id?: string;
-}
 interface JobCreateResponse {
     job_id: string;
     conversation_id: string;
     message_id: string;
     status: string;
 }
+interface JobStatus {
+    jobId: string;
+    status: string;
+    createdAt: string | null;
+    startedAt: string | null;
+    completedAt: string | null;
+    errorMessage: string | null;
+    inputTokens: number;
+    outputTokens: number;
+}
+interface ActiveJob {
+    jobId: string | null;
+    status: string;
+}
+interface JobSummary {
+    jobId: string;
+    status: string;
+    replacesJobId: string | null;
+    responseContent: Record<string, unknown> | null;
+    metrics: Record<string, unknown> | null;
+    createdAt: string | null;
+}
+interface FeedbackRequest {
+    /** 1 for thumbs up, -1 for thumbs down. */
+    rating: 1 | -1;
+    comment?: string | null;
+}
+interface FeedbackResponse {
+    id: string;
+    jobId: string;
+    rating: number;
+    comment: string | null;
+    createdAt: string;
+}
 interface ChatStreamRequest {
     message?: string;
     conversation_id?: string;
@@ -663,6 +620,7 @@ interface ChatStreamRequest {
     upload_ids?: string[];
     agent_name?: string;
     enable_search?: boolean;
+    plan_mode?: boolean;
 }
 interface ToolResultRequest {
     conversation_id: string;
@@ -675,6 +633,35 @@ interface ToolResult {
     result: string;
     is_error: boolean;
 }
+type ToolApprovalDecision = "allow" | "deny";
+type ToolApprovalScope = "once" | "conversation" | "always";
+interface ToolApprovalRequest {
+    job_id: string;
+    call_id: string;
+    decision: ToolApprovalDecision;
+    scope: ToolApprovalScope;
+}
+/**
+ * A remembered tool-permission grant belonging to the current end user.
+ * Only `conversation`/`always` grants are ever stored (`once` is consumed at
+ * approval time and never persisted).
+ */
+interface ToolGrant {
+    id: string;
+    toolName: string;
+    decision: ToolApprovalDecision;
+    scope: Exclude<ToolApprovalScope, "once">;
+    /** Set for `conversation`-scoped grants; `null` for `always`. */
+    conversationId: string | null;
+    createdAt: string;
+}
+/** A page of the current end user's own tool grants. */
+interface MyToolGrantsPage {
+    grants: ToolGrant[];
+    total: number;
+    limit: number;
+    offset: number;
+}
 interface ToolDefinition {
     name: string;
     description: string;
@@ -711,6 +698,7 @@ interface SendOptions$1 {
     uploadIds?: string[];
     agentName?: string;
     enableSearch?: boolean;
+    planMode?: boolean;
 }
 interface ConversationAsset {
     id: string;
@@ -725,11 +713,53 @@ interface ConversationAsset {
 }
 
 declare class AstralformClient {
-    private readonly apiKey;
     private readonly baseURL;
-    private readonly userId;
     private readonly fetchFn;
+    /**
+     * Auth state is mutable so callers can rotate access tokens or switch
+     * project context without re-instantiating the client. API-key mode is
+     * effectively immutable in practice but uses the same shape for uniformity.
+     */
+    private auth;
     constructor(config: AstralformConfig);
+    /**
+     * Replace the current OIDC access token without reconstructing the client.
+     * Use after refreshing via the host's token manager (e.g., Supabase JS SDK).
+     * Throws if the client was created in API-key mode.
+     */
+    updateAccessToken(accessToken: string): void;
+    /**
+     * Swap the active project for a user-token client. The backend verifies the
+     * current developer has access to the new project; a 403 comes back if not.
+     */
+    updateProjectId(projectId: string): void;
+    /**
+     * Set (or clear) the end-user override for user-token mode.
+     *
+     * Pass `null` or an empty string to clear — subsequent requests go
+     * back to scoping against the developer's own identity. Throws if
+     * called in API-key mode, where end-user context already travels via
+     * the constructor's `userId` field.
+     */
+    updateEndUserId(endUserId: string | null): void;
+    /** Current end-user override in user-token mode, or `null` if unset. */
+    get endUserId(): string | null;
+    /**
+     * Active project for user-token mode, or `null` if pre-pick (client
+     * was constructed without one). For API-key mode the project is baked
+     * into the key, so this getter returns `null` there too — use
+     * `authMode` to disambiguate.
+     */
+    get projectId(): string | null;
+    /** Which auth mode this client was constructed with. */
+    get authMode(): "api_key" | "user_token";
+    /**
+     * Authorization + identity headers for the current auth mode, without
+     * `Content-Type`. Suitable for JSON requests (paired with the JSON header
+     * in the `headers` getter) and for multipart uploads where the browser
+     * must set its own `Content-Type` boundary.
+     */
+    private get authHeaders();
     private get headers();
     private request;
     get<T>(path: string): Promise<T>;
@@ -749,13 +779,61 @@ declare class AstralformClient {
     getSkills(): Promise<SkillInfo[]>;
     getConversationEvents(conversationId: string, jobId?: string): Promise<ConversationEvent[]>;
     submitToolResult(request: ToolResultRequest): Promise<void>;
+    submitToolApproval(request: ToolApprovalRequest): Promise<void>;
+    /**
+     * List the current end user's own remembered tool-permission grants.
+     * Only `conversation`/`always` grants exist (`once` is never persisted).
+     * Paginated via `limit` (default 100, max 200) / `offset`; `total` lets you
+     * page through all of them.
+     */
+    getMyToolPermissions(options?: {
+        limit?: number;
+        offset?: number;
+    }): Promise<MyToolGrantsPage>;
+    /**
+     * Revoke one of the current end user's remembered grants by id. The agent
+     * will ask again the next time that tool is used.
+     */
+    revokeToolPermission(id: string): Promise<void>;
     private mapAsset;
     uploadFile(conversationId: string, file: Blob, filename?: string): Promise<ConversationAsset>;
     listUploads(conversationId: string): Promise<ConversationAsset[]>;
     listOutputs(conversationId: string): Promise<ConversationAsset[]>;
+    listTeams(): Promise<TeamSummary[]>;
+    listProjects(teamId: string): Promise<ProjectSummary[]>;
     createJob(request: ChatStreamRequest): Promise<JobCreateResponse>;
     streamJobEvents(jobId: string, afterSeq?: number, signal?: AbortSignal): AsyncGenerator<ChatStreamEvent>;
     cancelJob(jobId: string): Promise<void>;
+    getJob(jobId: string): Promise<JobStatus>;
+    submitFeedback(jobId: string, request: FeedbackRequest): Promise<FeedbackResponse>;
+    getActiveJob(conversationId: string): Promise<ActiveJob>;
+    listJobs(conversationId: string): Promise<JobSummary[]>;
+}
+
+/**
+ * Minimal adapter contract. Frontends extend this with a `render()`
+ * method (or equivalent) returning their framework's view type.
+ */
+interface ProtocolAdapter {
+    /** IANA-style MIME type this adapter handles (e.g. ``application/json+a2ui``). */
+    readonly mimeType: string;
+}
+/**
+ * MIME-keyed adapter map, generic on the adapter subtype so consumers
+ * can register richer shapes without casting on every read.
+ */
+declare class ProtocolRegistry<T extends ProtocolAdapter = ProtocolAdapter> {
+    private adapters;
+    /** Register or replace the adapter for a MIME type. */
+    register(adapter: T): void;
+    /** Remove the adapter for a MIME type. No-op if not registered. */
+    unregister(mimeType: string): void;
+    /** Returns the adapter for a MIME type, or ``null`` if none is registered. */
+    get(mimeType: string): T | null;
+    has(mimeType: string): boolean;
+    /** Drop every adapter. Called when a session disconnects. */
+    clear(): void;
+    listMimeTypes(): string[];
 }
 
 interface ChatStorage {
@@ -796,31 +874,38 @@ declare class ToolRegistry {
 }
 
 type ChatEventHandler = (event: ChatEvent) => void;
+/**
+ * ChatSession — translates the backend wire protocol into typed ChatEvents
+ * for consumers. Owns HTTP + SSE plumbing, conversation state, and the
+ * client-tool round-trip. Does NOT own block construction — consumers
+ * build their own block state from the typed events.
+ */
 declare class ChatSession {
     readonly client: AstralformClient;
     readonly toolRegistry: ToolRegistry;
     readonly storage: ChatStorage;
-    readonly blockBuilder: BlockBuilder;
+    /**
+     * Pluggable UI protocol adapters. Consumers register a framework-
+     * specific adapter (e.g. React) for each MIME type they can render,
+     * typically gated on ``session.projectStatus.uiComponents.protocol``.
+     * ``ToolBlock``-style consumers look up the adapter for an incoming
+     * embedded resource and hand off rendering.
+     */
+    readonly protocols: ProtocolRegistry<ProtocolAdapter>;
     conversationId: string | null;
     conversations: Conversation[];
     messages: Message[];
-    streamingContent: string;
     isStreaming: boolean;
-    executingTool: string | null;
     projectStatus: ProjectStatus | null;
     agents: AgentInfo[];
     skills: SkillInfo[];
     enabledClientTools: Set<string>;
     modelDisplayName: string | null;
-    thinkingContent: string;
-    isThinking: boolean;
-    activeSubagents: Map<string, SubagentState>;
-    capsuleOutputs: CapsuleOutput[];
-    todos: TodoItem[];
-    activeTools: Map<string, ToolState>;
+    private accumulatedText;
+    private currentTextPath;
     private handlers;
     private abortController;
-    constructor(config: AstralformConfig, storage?: ChatStorage, blockBuilder?: BlockBuilder);
+    constructor(config: AstralformConfig, storage?: ChatStorage);
     on(handler: ChatEventHandler): () => void;
     private emit;
     connect(): Promise<void>;
@@ -836,16 +921,22 @@ declare class ChatSession {
     currentJobId: string | null;
     private consumeJobStream;
     /**
-     * Shared event consumption loop used by both consumeJobStream and reconnectToJob.
+     * Shared event consumption loop. Parses each wire event, updates
+     * minimal session state, and emits typed ChatEvents to consumers.
      */
     private consumeEventStream;
+    private dispatchWireEvent;
     /**
-     * Apply a single SSE event to session state and notify consumers.
-     * Shared between live streaming and historical event replay.
+     * State mutations driven by wire events. Kept separate from translation so
+     * the pure wire → ChatEvent mapping can live in translate.ts and be reused
+     * by the replay path.
+     *
+     * ``messageId`` is the server-assigned assistant message id for the current
+     * turn; empty in the reconnect and conversation-switch replay paths where
+     * messages have already been loaded from REST and shouldn't be re-pushed.
      */
-    private applyEvent;
+    private applyWireSideEffects;
     private executeClientTools;
-    private completeStream;
     /**
      * Load conversation context (messages) without replaying events.
      * Used before reconnectToJob — SSE replay handles event replay.
@@ -854,33 +945,35 @@ declare class ChatSession {
     /**
      * Reconnect to a running job's SSE stream (e.g. after page reload).
      * Replays all events from the beginning and continues live.
-     * Does NOT reset BlockBuilder — caller controls reset.
      */
     reconnectToJob(jobId: string): Promise<void>;
-    /** Detach from the SSE stream without cancelling the job.
-     *  The backend job keeps running — caller can reconnect later. */
+    /** Detach from the SSE stream without cancelling the job. */
     detach(): void;
     /** Stop the job and disconnect (explicit user action). */
     disconnect(): void;
     createNewConversation(): Promise<string>;
-    switchConversation(id: string, jobId?: string): Promise<void>;
+    switchConversation(id: string, jobId?: string, 
+    /**
+     * User prompt that triggered this job, if known. Emitted as a
+     * synthetic ``user_message`` ChatEvent right before the first
+     * ``message_start`` of the replay. User messages aren't persisted
+     * in ``job_events``, so without this the restored conversation
+     * would show the agent response with no visible prompt above it.
+     */
+    userMessageContent?: string): Promise<void>;
     deleteConversation(id: string): Promise<void>;
     toggleClientTool(name: string): boolean;
 }
 
-/**
- * Standard event handlers for BlockBuilder.
- *
- * These define the default event→block mapping rules. Clients import
- * and register them explicitly:
- *
- *   import { BlockBuilder, standardHandlers } from "@astralform/js";
- *   const builder = new BlockBuilder();
- *   builder.registerHandlers(standardHandlers);
- */
-
-declare const standardHandlers: Record<string, EventHandler$1>;
-
+interface RateLimitErrorDetails {
+    retryAfterSec?: number;
+    resetAt?: number;
+    scope?: string;
+    policyId?: string;
+    limit?: number;
+    remaining?: number;
+    requestId?: string;
+}
 declare class AstralformError extends Error {
     code: string;
     constructor(message: string, code: string);
@@ -889,7 +982,14 @@ declare class AuthenticationError extends AstralformError {
     constructor(message?: string);
 }
 declare class RateLimitError extends AstralformError {
-    constructor(message?: string);
+    readonly retryAfterSec?: number;
+    readonly resetAt?: number;
+    readonly scope?: string;
+    readonly policyId?: string;
+    readonly limit?: number;
+    readonly remaining?: number;
+    readonly requestId?: string;
+    constructor(message?: string, details?: RateLimitErrorDetails);
 }
 declare class LLMNotConfiguredError extends AstralformError {
     constructor(message?: string);
@@ -916,12 +1016,18 @@ declare function streamJobSSE(options: StreamJobSSEOptions): AsyncGenerator<Chat
  *
  * Sits on top of ChatSession and manages the state machine for
  * multi-conversation SSE streaming. Framework-agnostic: emits
- * callbacks instead of writing to any state management library.
+ * typed events to registered handlers. Block construction is NOT
+ * the SDK's concern — consumers build their own block tree from
+ * the forwarded ``ChatEvent`` instances.
  *
  *   import { ChatSession, StreamManager } from "@astralform/js";
  *   const session = new ChatSession({ ... });
  *   const manager = new StreamManager(session);
- *   manager.on("blocksChanged", (convId, blocks) => { ... });
+ *   manager.on((event) => {
+ *     if (event.type === "event") {
+ *       // event.event is a typed ChatEvent — dispatch to your reducer
+ *     }
+ *   });
  *   await manager.send("Hello");
  */
 
@@ -930,15 +1036,12 @@ interface SendOptions {
     enableSearch?: boolean;
     agentName?: string;
     uploadIds?: string[];
+    planMode?: boolean;
 }
 type StreamManagerEvent = {
     type: "stateChange";
     state: StreamState;
     conversationId: string | null;
-} | {
-    type: "blocksChanged";
-    conversationId: string;
-    blocks: Block[];
 } | {
     type: "conversationChanged";
     conversationId: string | null;
@@ -978,10 +1081,81 @@ declare class StreamManager {
     deleteConversation(id: string): Promise<void>;
     stop(): void;
     destroy(): void;
-    private prepareUserBlock;
     private finalizeStream;
     private restore;
     private setActiveConversation;
 }
 
-export { type AgentBlock, type AgentEndEvent, type AgentInfo, type AgentStartEvent, type AssetBlock, AstralformClient, type AstralformConfig, AstralformError, type AttachmentBlock, type AttachmentStagedEvent, AuthenticationError, type Block, BlockBuilder, type CapsuleBlock, type CapsuleOutput, type CapsuleOutputChunkEvent, type CapsuleOutputEvent, type ChatEvent, ChatEventType, ChatSession, type ChatStorage, type ChatStreamEvent, type ChatStreamRequest, ConnectionError, type ContentBlockDeltaEvent, type Conversation, type ConversationAsset, type ConversationEvent, type DesktopStreamBlock, type DesktopStreamEvent, type EditorBlock, type ErrorBlock, type EventHandler$1 as EventHandler, InMemoryStorage, type JobCreateResponse, LLMNotConfiguredError, type Message, type MessageStartEvent, type MessageStopEvent, type ProjectStatus, RateLimitError, type RetryEvent, type SSEErrorEvent, type SSEEvent, type SendOptions, ServerError, type SkillInfo, type Source, StreamAbortedError, type StreamJobSSEOptions, StreamManager, type StreamManagerEvent, type StreamState, type SubagentBlock, type SubagentContentDeltaEvent, type SubagentEndEvent, type SubagentStartEvent, type SubagentState, type SubagentToolUseEvent, type TextBlock, type ThinkingBlock, type ThinkingCompleteEvent, type ThinkingDeltaEvent, type TodoBlock, type TodoItem, type TodoUpdateEvent, type ToolBlock, type ToolCallRequest, type ToolDefinition, type ToolExecutingEvent, type ToolHandler, type ToolProgressEvent, ToolRegistry, type ToolResult, type ToolResultRequest, type ToolState, type ToolUseEndEvent, type ToolUseStartEvent, type UserBlock, type WorkspaceReadyEvent, generateId, standardHandlers, streamJobSSE };
+/**
+ * Translate a WireBlockDeltaPayload into the consumer-facing shape. Returns
+ * ``null`` for unknown channels so forward-compatible backends can add new
+ * ones without breaking old clients.
+ */
+declare function translateDelta(wire: WireBlockDeltaPayload): BlockDeltaPayload | null;
+
+/**
+ * Raw SSE event shape returned by GET /v1/conversations/{id}/events.
+ * Mirrors what JobEventWriter persists to the job_events table.
+ */
+interface RawSseEvent {
+    seq: number;
+    event: string;
+    data: Record<string, unknown>;
+    /** Epoch ms when the event was persisted (from job_events.created_at). */
+    created_at?: number;
+}
+/**
+ * Map a raw SSE event (persisted in job_events) into the SDK ChatEvent
+ * format. Returns an array because some rows (malformed / ``done`` sentinels)
+ * map to zero events.
+ */
+declare function mapSseToChat(raw: RawSseEvent): ChatEvent[];
+/**
+ * Replay persisted SSE events through the provided handler, interleaving
+ * user messages from session.messages at the first message_start of each
+ * turn (user messages aren't persisted in job_events).
+ */
+declare function replayEvents(sseEvents: RawSseEvent[], userMessages: {
+    role: string;
+    content: string;
+}[], handleEvent: (event: ChatEvent) => void, addBlock: (block: {
+    type: "user";
+    id: string;
+    content: string;
+}) => void): void;
+
+/**
+ * Parsed shape of an MCP-style embedded resource, as emitted by the
+ * backend's UI component tools (``render_surface``, ``update_surface``).
+ */
+interface EmbeddedResource {
+    /** IANA-style MIME type, e.g. "application/json+a2ui". */
+    mimeType: string;
+    /** Opaque URI (e.g. "a2ui://surface/my-form"). */
+    uri: string;
+    /** Protocol-specific payload — shape depends on ``mimeType``. */
+    payload: Record<string, unknown>;
+}
+/**
+ * Detect whether a value is an embedded resource wrapper. The check is
+ * purposely loose — any object with ``_embedded_resource: true`` is
+ * accepted, which matches the MCP convention and keeps the SDK
+ * forward-compatible with future protocols.
+ */
+declare function isEmbeddedResource(value: unknown): value is {
+    _embedded_resource: true;
+    mime_type?: string;
+    uri?: string;
+    payload?: Record<string, unknown>;
+};
+/**
+ * Parse an embedded resource from arbitrary tool output. Returns
+ * ``null`` when the value isn't an embedded resource or is malformed.
+ *
+ * Accepts either an object (the preferred wire format) or a JSON
+ * string containing one (defense in depth — some transport layers
+ * historically serialized tool results before sending).
+ */
+declare function parseEmbeddedResource(value: unknown): EmbeddedResource | null;
+
+export { type ActiveJob, type AgentIdentity, type AgentInfo, type AssetCreatedPayload, type AstralformApiKeyConfig, AstralformClient, type AstralformConfig, AstralformError, type AstralformUserTokenConfig, type AttachmentStagedPayload, AuthenticationError, type BlockDeltaPayload, 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 EmbeddedResource, type FeedbackRequest, type FeedbackResponse, InMemoryStorage, type JobCreateResponse, type JobStatus, type JobSummary, LLMNotConfiguredError, type MemoryRecallPayload, type MemoryRecord, type MemoryUpdatePayload, type Message, type MyToolGrantsPage, type ProjectStatus, type ProjectSummary, type PromptSuggestionPayload, type ProtocolAdapter, ProtocolRegistry, RateLimitError, type RateLimitErrorDetails, type RawSseEvent, type SendOptions, ServerError, type SkillInfo, StreamAbortedError, type StreamJobSSEOptions, StreamManager, type StreamManagerEvent, type StreamState, type SubagentStartPayload, type SubagentStopPayload, type TaskStatus, type TeamSummary, 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 };