@belonguniverseai/react-sdk 0.1.0

package/dist/stream/belong-chat-transport.d.ts

@@ -0,0 +1,679 @@
+import { z } from 'zod';
+import { ChatTransport, UIMessageChunk } from 'ai';
+import { BelongUIMessage, WireStreamPart } from './belong-data-parts.ts';
+/**
+ * The wire/stored part union. Exported so the history loader (chat.tsx) can
+ * validate persisted assistant parts against the SAME shapes the live stream
+ * uses — one source of truth, no drift between live and reloaded renders
+ * (BEL-48). The history route returns these verbatim for assistant turns that
+ * carry folded parts.
+ */
+export declare const wireStreamPartSchema: z.ZodDiscriminatedUnion<"type", [z.ZodObject<{
+    type: z.ZodLiteral<"text">;
+    id: z.ZodString;
+    text: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    id: string;
+    type: "text";
+    text: string;
+}, {
+    id: string;
+    type: "text";
+    text: string;
+}>, z.ZodObject<{
+    type: z.ZodLiteral<"data-reasoning">;
+    id: z.ZodString;
+    data: z.ZodObject<{
+        delta: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        delta: string;
+    }, {
+        delta: string;
+    }>;
+}, "strip", z.ZodTypeAny, {
+    id: string;
+    data: {
+        delta: string;
+    };
+    type: "data-reasoning";
+}, {
+    id: string;
+    data: {
+        delta: string;
+    };
+    type: "data-reasoning";
+}>, z.ZodObject<{
+    type: z.ZodLiteral<"data-plan">;
+    id: z.ZodString;
+    data: z.ZodObject<{
+        title: z.ZodString;
+        summary: z.ZodString;
+        steps: z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            title: z.ZodString;
+            kind: z.ZodString;
+            status: z.ZodOptional<z.ZodEnum<["pending", "in_progress", "completed", "failed"]>>;
+        }, "strip", z.ZodTypeAny, {
+            id: string;
+            title: string;
+            kind: string;
+            status?: "pending" | "completed" | "failed" | "in_progress" | undefined;
+        }, {
+            id: string;
+            title: string;
+            kind: string;
+            status?: "pending" | "completed" | "failed" | "in_progress" | undefined;
+        }>, "many">;
+    }, "strip", z.ZodTypeAny, {
+        title: string;
+        summary: string;
+        steps: {
+            id: string;
+            title: string;
+            kind: string;
+            status?: "pending" | "completed" | "failed" | "in_progress" | undefined;
+        }[];
+    }, {
+        title: string;
+        summary: string;
+        steps: {
+            id: string;
+            title: string;
+            kind: string;
+            status?: "pending" | "completed" | "failed" | "in_progress" | undefined;
+        }[];
+    }>;
+}, "strip", z.ZodTypeAny, {
+    id: string;
+    data: {
+        title: string;
+        summary: string;
+        steps: {
+            id: string;
+            title: string;
+            kind: string;
+            status?: "pending" | "completed" | "failed" | "in_progress" | undefined;
+        }[];
+    };
+    type: "data-plan";
+}, {
+    id: string;
+    data: {
+        title: string;
+        summary: string;
+        steps: {
+            id: string;
+            title: string;
+            kind: string;
+            status?: "pending" | "completed" | "failed" | "in_progress" | undefined;
+        }[];
+    };
+    type: "data-plan";
+}>, z.ZodObject<{
+    type: z.ZodLiteral<"data-approval-request">;
+    id: z.ZodString;
+    data: z.ZodObject<{
+        approvalId: z.ZodString;
+        reason: z.ZodString;
+        state: z.ZodEnum<["pending", "approved", "rejected", "amend_requested", "expired"]>;
+        toolName: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        reason: string;
+        approvalId: string;
+        state: "pending" | "approved" | "rejected" | "amend_requested" | "expired";
+        toolName?: string | undefined;
+    }, {
+        reason: string;
+        approvalId: string;
+        state: "pending" | "approved" | "rejected" | "amend_requested" | "expired";
+        toolName?: string | undefined;
+    }>;
+}, "strip", z.ZodTypeAny, {
+    id: string;
+    data: {
+        reason: string;
+        approvalId: string;
+        state: "pending" | "approved" | "rejected" | "amend_requested" | "expired";
+        toolName?: string | undefined;
+    };
+    type: "data-approval-request";
+}, {
+    id: string;
+    data: {
+        reason: string;
+        approvalId: string;
+        state: "pending" | "approved" | "rejected" | "amend_requested" | "expired";
+        toolName?: string | undefined;
+    };
+    type: "data-approval-request";
+}>, z.ZodObject<{
+    type: z.ZodLiteral<"data-tool-call">;
+    id: z.ZodString;
+    data: z.ZodObject<{
+        toolName: z.ZodString;
+        state: z.ZodEnum<["started", "completed", "failed"]>;
+        input: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        output: z.ZodOptional<z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+        error: z.ZodOptional<z.ZodObject<{
+            code: z.ZodString;
+            message: z.ZodString;
+            severity: z.ZodOptional<z.ZodEnum<["error", "stop"]>>;
+        }, "strip", z.ZodTypeAny, {
+            message: string;
+            code: string;
+            severity?: "error" | "stop" | undefined;
+        }, {
+            message: string;
+            code: string;
+            severity?: "error" | "stop" | undefined;
+        }>>;
+    }, "strip", z.ZodTypeAny, {
+        toolName: string;
+        state: "completed" | "failed" | "started";
+        input?: Record<string, unknown> | undefined;
+        output?: Record<string, unknown> | null | undefined;
+        error?: {
+            message: string;
+            code: string;
+            severity?: "error" | "stop" | undefined;
+        } | undefined;
+    }, {
+        toolName: string;
+        state: "completed" | "failed" | "started";
+        input?: Record<string, unknown> | undefined;
+        output?: Record<string, unknown> | null | undefined;
+        error?: {
+            message: string;
+            code: string;
+            severity?: "error" | "stop" | undefined;
+        } | undefined;
+    }>;
+}, "strip", z.ZodTypeAny, {
+    id: string;
+    data: {
+        toolName: string;
+        state: "completed" | "failed" | "started";
+        input?: Record<string, unknown> | undefined;
+        output?: Record<string, unknown> | null | undefined;
+        error?: {
+            message: string;
+            code: string;
+            severity?: "error" | "stop" | undefined;
+        } | undefined;
+    };
+    type: "data-tool-call";
+}, {
+    id: string;
+    data: {
+        toolName: string;
+        state: "completed" | "failed" | "started";
+        input?: Record<string, unknown> | undefined;
+        output?: Record<string, unknown> | null | undefined;
+        error?: {
+            message: string;
+            code: string;
+            severity?: "error" | "stop" | undefined;
+        } | undefined;
+    };
+    type: "data-tool-call";
+}>, z.ZodObject<{
+    type: z.ZodLiteral<"data-sandbox-command">;
+    id: z.ZodString;
+    data: z.ZodObject<{
+        state: z.ZodEnum<["started", "output", "completed", "failed"]>;
+        stream: z.ZodOptional<z.ZodEnum<["stdout", "stderr"]>>;
+        delta: z.ZodOptional<z.ZodString>;
+        exitCode: z.ZodOptional<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        state: "output" | "completed" | "failed" | "started";
+        delta?: string | undefined;
+        stream?: "stdout" | "stderr" | undefined;
+        exitCode?: number | undefined;
+    }, {
+        state: "output" | "completed" | "failed" | "started";
+        delta?: string | undefined;
+        stream?: "stdout" | "stderr" | undefined;
+        exitCode?: number | undefined;
+    }>;
+}, "strip", z.ZodTypeAny, {
+    id: string;
+    data: {
+        state: "output" | "completed" | "failed" | "started";
+        delta?: string | undefined;
+        stream?: "stdout" | "stderr" | undefined;
+        exitCode?: number | undefined;
+    };
+    type: "data-sandbox-command";
+}, {
+    id: string;
+    data: {
+        state: "output" | "completed" | "failed" | "started";
+        delta?: string | undefined;
+        stream?: "stdout" | "stderr" | undefined;
+        exitCode?: number | undefined;
+    };
+    type: "data-sandbox-command";
+}>, z.ZodObject<{
+    type: z.ZodLiteral<"data-ui-action">;
+    id: z.ZodString;
+    data: z.ZodObject<{
+        uiActionRequestId: z.ZodString;
+        actionName: z.ZodString;
+        state: z.ZodEnum<["requested", "completed", "failed"]>;
+        args: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    }, "strip", z.ZodTypeAny, {
+        state: "completed" | "failed" | "requested";
+        uiActionRequestId: string;
+        actionName: string;
+        args?: Record<string, unknown> | undefined;
+    }, {
+        state: "completed" | "failed" | "requested";
+        uiActionRequestId: string;
+        actionName: string;
+        args?: Record<string, unknown> | undefined;
+    }>;
+}, "strip", z.ZodTypeAny, {
+    id: string;
+    data: {
+        state: "completed" | "failed" | "requested";
+        uiActionRequestId: string;
+        actionName: string;
+        args?: Record<string, unknown> | undefined;
+    };
+    type: "data-ui-action";
+}, {
+    id: string;
+    data: {
+        state: "completed" | "failed" | "requested";
+        uiActionRequestId: string;
+        actionName: string;
+        args?: Record<string, unknown> | undefined;
+    };
+    type: "data-ui-action";
+}>, z.ZodObject<{
+    type: z.ZodLiteral<"data-cli-reconnect">;
+    id: z.ZodString;
+    data: z.ZodObject<{
+        provider: z.ZodString;
+        scopeExternalId: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        provider: string;
+        scopeExternalId: string;
+    }, {
+        provider: string;
+        scopeExternalId: string;
+    }>;
+}, "strip", z.ZodTypeAny, {
+    id: string;
+    data: {
+        provider: string;
+        scopeExternalId: string;
+    };
+    type: "data-cli-reconnect";
+}, {
+    id: string;
+    data: {
+        provider: string;
+        scopeExternalId: string;
+    };
+    type: "data-cli-reconnect";
+}>, z.ZodObject<{
+    type: z.ZodLiteral<"data-navigation">;
+    id: z.ZodString;
+    data: z.ZodObject<{
+        routeName: z.ZodString;
+        params: z.ZodRecord<z.ZodString, z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        params: Record<string, string>;
+        routeName: string;
+    }, {
+        params: Record<string, string>;
+        routeName: string;
+    }>;
+}, "strip", z.ZodTypeAny, {
+    id: string;
+    data: {
+        params: Record<string, string>;
+        routeName: string;
+    };
+    type: "data-navigation";
+}, {
+    id: string;
+    data: {
+        params: Record<string, string>;
+        routeName: string;
+    };
+    type: "data-navigation";
+}>, z.ZodObject<{
+    type: z.ZodLiteral<"data-artifact">;
+    id: z.ZodString;
+    data: z.ZodObject<{
+        artifactId: z.ZodString;
+        title: z.ZodString;
+        mimeType: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        title: string;
+        artifactId: string;
+        mimeType: string;
+    }, {
+        title: string;
+        artifactId: string;
+        mimeType: string;
+    }>;
+}, "strip", z.ZodTypeAny, {
+    id: string;
+    data: {
+        title: string;
+        artifactId: string;
+        mimeType: string;
+    };
+    type: "data-artifact";
+}, {
+    id: string;
+    data: {
+        title: string;
+        artifactId: string;
+        mimeType: string;
+    };
+    type: "data-artifact";
+}>, z.ZodObject<{
+    type: z.ZodLiteral<"data-status">;
+    id: z.ZodString;
+    data: z.ZodObject<{
+        status: z.ZodEnum<["continuing", "completed", "cancelled", "failed", "throttled"]>;
+        message: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        status: "completed" | "failed" | "cancelled" | "continuing" | "throttled";
+        message?: string | undefined;
+    }, {
+        status: "completed" | "failed" | "cancelled" | "continuing" | "throttled";
+        message?: string | undefined;
+    }>;
+}, "strip", z.ZodTypeAny, {
+    id: string;
+    data: {
+        status: "completed" | "failed" | "cancelled" | "continuing" | "throttled";
+        message?: string | undefined;
+    };
+    type: "data-status";
+}, {
+    id: string;
+    data: {
+        status: "completed" | "failed" | "cancelled" | "continuing" | "throttled";
+        message?: string | undefined;
+    };
+    type: "data-status";
+}>, z.ZodObject<{
+    type: z.ZodLiteral<"data-usage">;
+    id: z.ZodString;
+    data: z.ZodObject<{
+        inputTokens: z.ZodNumber;
+        outputTokens: z.ZodNumber;
+        totalTokens: z.ZodNumber;
+        historyChars: z.ZodNumber;
+        autoCompactThresholdChars: z.ZodNumber;
+    }, "strip", z.ZodTypeAny, {
+        inputTokens: number;
+        outputTokens: number;
+        totalTokens: number;
+        historyChars: number;
+        autoCompactThresholdChars: number;
+    }, {
+        inputTokens: number;
+        outputTokens: number;
+        totalTokens: number;
+        historyChars: number;
+        autoCompactThresholdChars: number;
+    }>;
+}, "strip", z.ZodTypeAny, {
+    id: string;
+    data: {
+        inputTokens: number;
+        outputTokens: number;
+        totalTokens: number;
+        historyChars: number;
+        autoCompactThresholdChars: number;
+    };
+    type: "data-usage";
+}, {
+    id: string;
+    data: {
+        inputTokens: number;
+        outputTokens: number;
+        totalTokens: number;
+        historyChars: number;
+        autoCompactThresholdChars: number;
+    };
+    type: "data-usage";
+}>, z.ZodObject<{
+    type: z.ZodLiteral<"data-choice-request">;
+    id: z.ZodString;
+    data: z.ZodDiscriminatedUnion<"mode", [z.ZodObject<{
+        mode: z.ZodLiteral<"single">;
+        uiActionRequestId: z.ZodString;
+        question: z.ZodString;
+        options: z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            label: z.ZodString;
+            description: z.ZodOptional<z.ZodString>;
+        }, "strip", z.ZodTypeAny, {
+            id: string;
+            label: string;
+            description?: string | undefined;
+        }, {
+            id: string;
+            label: string;
+            description?: string | undefined;
+        }>, "many">;
+        state: z.ZodEnum<["pending", "resolved", "expired"]>;
+    }, "strip", z.ZodTypeAny, {
+        mode: "single";
+        options: {
+            id: string;
+            label: string;
+            description?: string | undefined;
+        }[];
+        state: "pending" | "expired" | "resolved";
+        uiActionRequestId: string;
+        question: string;
+    }, {
+        mode: "single";
+        options: {
+            id: string;
+            label: string;
+            description?: string | undefined;
+        }[];
+        state: "pending" | "expired" | "resolved";
+        uiActionRequestId: string;
+        question: string;
+    }>, z.ZodObject<{
+        mode: z.ZodLiteral<"multi">;
+        uiActionRequestId: z.ZodString;
+        question: z.ZodString;
+        options: z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            label: z.ZodString;
+            description: z.ZodOptional<z.ZodString>;
+        }, "strip", z.ZodTypeAny, {
+            id: string;
+            label: string;
+            description?: string | undefined;
+        }, {
+            id: string;
+            label: string;
+            description?: string | undefined;
+        }>, "many">;
+        state: z.ZodEnum<["pending", "resolved", "expired"]>;
+        minChoicesCount: z.ZodOptional<z.ZodNumber>;
+        maxChoicesCount: z.ZodOptional<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        mode: "multi";
+        options: {
+            id: string;
+            label: string;
+            description?: string | undefined;
+        }[];
+        state: "pending" | "expired" | "resolved";
+        uiActionRequestId: string;
+        question: string;
+        minChoicesCount?: number | undefined;
+        maxChoicesCount?: number | undefined;
+    }, {
+        mode: "multi";
+        options: {
+            id: string;
+            label: string;
+            description?: string | undefined;
+        }[];
+        state: "pending" | "expired" | "resolved";
+        uiActionRequestId: string;
+        question: string;
+        minChoicesCount?: number | undefined;
+        maxChoicesCount?: number | undefined;
+    }>, z.ZodObject<{
+        mode: z.ZodLiteral<"open">;
+        uiActionRequestId: z.ZodString;
+        question: z.ZodString;
+        state: z.ZodEnum<["pending", "resolved", "expired"]>;
+        placeholder: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        mode: "open";
+        state: "pending" | "expired" | "resolved";
+        uiActionRequestId: string;
+        question: string;
+        placeholder?: string | undefined;
+    }, {
+        mode: "open";
+        state: "pending" | "expired" | "resolved";
+        uiActionRequestId: string;
+        question: string;
+        placeholder?: string | undefined;
+    }>]>;
+}, "strip", z.ZodTypeAny, {
+    id: string;
+    data: {
+        mode: "single";
+        options: {
+            id: string;
+            label: string;
+            description?: string | undefined;
+        }[];
+        state: "pending" | "expired" | "resolved";
+        uiActionRequestId: string;
+        question: string;
+    } | {
+        mode: "multi";
+        options: {
+            id: string;
+            label: string;
+            description?: string | undefined;
+        }[];
+        state: "pending" | "expired" | "resolved";
+        uiActionRequestId: string;
+        question: string;
+        minChoicesCount?: number | undefined;
+        maxChoicesCount?: number | undefined;
+    } | {
+        mode: "open";
+        state: "pending" | "expired" | "resolved";
+        uiActionRequestId: string;
+        question: string;
+        placeholder?: string | undefined;
+    };
+    type: "data-choice-request";
+}, {
+    id: string;
+    data: {
+        mode: "single";
+        options: {
+            id: string;
+            label: string;
+            description?: string | undefined;
+        }[];
+        state: "pending" | "expired" | "resolved";
+        uiActionRequestId: string;
+        question: string;
+    } | {
+        mode: "multi";
+        options: {
+            id: string;
+            label: string;
+            description?: string | undefined;
+        }[];
+        state: "pending" | "expired" | "resolved";
+        uiActionRequestId: string;
+        question: string;
+        minChoicesCount?: number | undefined;
+        maxChoicesCount?: number | undefined;
+    } | {
+        mode: "open";
+        state: "pending" | "expired" | "resolved";
+        uiActionRequestId: string;
+        question: string;
+        placeholder?: string | undefined;
+    };
+    type: "data-choice-request";
+}>]>;
+/** A request was 401'd twice (once with a freshly re-read token): the host
+ * session is expired — the dock must surface re-auth, not retry forever. */
+export declare const AUTH_EXPIRED_ERROR_PREFIX = "auth_expired:";
+/** The SSE reconnect loop exhausted its attempt budget without the backend
+ * delivering a single event — the service is unreachable. */
+export declare const BACKEND_UNAVAILABLE_ERROR_PREFIX = "backend_unavailable:";
+/** First reconnect delay — identical to the historic fixed delay, so the
+ * BEL-48 mid-run clean-EOF reconnect regains the stream just as fast. */
+export declare const RECONNECT_BASE_DELAY_MS = 1000;
+/** Exponential backoff ceiling. */
+export declare const RECONNECT_MAX_DELAY_MS = 30000;
+/** Consecutive connection attempts that deliver no event before we give up. */
+export declare const RECONNECT_MAX_CONSECUTIVE_FAILURES = 10;
+export type BelongChatTransportOptions = {
+    /** Belong cloud base URL, e.g. `http://localhost:8787`. */
+    readonly apiBaseUrl: string;
+    /**
+     * Reconnect delay seam (§25 — do not hide time). Tests inject an instant
+     * recorder; production uses a real setTimeout sleep.
+     */
+    readonly sleepMs?: (ms: number) => Promise<void>;
+};
+export type StreamContext = {
+    /** Stable id we emit on every `text-delta`. Null when no text run is open. */
+    textRunId: string | null;
+    /**
+     * Monotonic counter for text-run ids. A NEW id per run is what preserves
+     * order when text and tool calls interleave: a tool call closes the open run,
+     * so the text that follows opens a fresh part AFTER the tool part. Reusing one
+     * id (or one derived from a repeatable wire id) would merge later text back
+     * into the first text part, floating tool activity to the bottom.
+     */
+    textRunSeq: number;
+    /**
+     * Stable id we emit on every `reasoning-delta`. Null when no reasoning run
+     * is open. Reasoning is its OWN prose run, parallel to text: the agent's
+     * thinking streams as one collapsible block, so consecutive
+     * `reasoning_chunk`s accumulate under one native `reasoning` part (the SDK
+     * appends same-id `reasoning-delta`s) instead of one block per delta.
+     */
+    reasoningRunId: string | null;
+    /** Monotonic counter for reasoning-run ids (see `textRunSeq`). */
+    reasoningRunSeq: number;
+    /** Latest server-issued SSE `id:` value — sent on reconnect. */
+    lastEventId: string | null;
+    /** Current chat-cloud run id; persisted so reconnect targets the same stream. */
+    runId: string | null;
+};
+export declare class BelongChatTransport implements ChatTransport<BelongUIMessage> {
+    #private;
+    constructor(options: BelongChatTransportOptions);
+    /** Drop the cached session so the next `sendMessages` creates a new one. */
+    reset(): void;
+    /**
+     * Best-effort server-side cancel of an in-flight run. `useChat`'s `stop()`
+     * only aborts the local stream (stops listening); this tells belong-cloud to
+     * actually halt the agent (POST /v1/runs/:runId/cancel → run-cancel pub/sub).
+     */
+    cancelRun: (runId: string) => Promise<void>;
+    sendMessages: ChatTransport<BelongUIMessage>["sendMessages"];
+    reconnectToStream: ChatTransport<BelongUIMessage>["reconnectToStream"];
+}
+export declare const wireToUiChunks: (part: WireStreamPart, ctx: StreamContext) => readonly UIMessageChunk[];