@x12i/ai 1.0.0 → 1.1.0

package/dist/stream-C2tzoSII.d.ts

@@ -0,0 +1,482 @@
+/**
+ * The neutral message shape (spec section 6). Components read typed parts and
+ * never import a provider SDK; adapters convert provider formats into this
+ * shape.
+ *
+ * Everything here is plain, JSON-serializable data, so a thread can be stored
+ * through `ThreadStore`, sent over the wire or kept in a database.
+ */
+type MessageRole = "user" | "assistant" | "system" | "tool";
+interface TextPart {
+    type: "text";
+    text: string;
+}
+interface ReasoningPart {
+    type: "reasoning";
+    text: string;
+    /** How long the model thought, for the "Thought for 4s" line. */
+    durationMs?: number;
+    /** Epoch milliseconds when this reasoning began. Set by the thread reducer. */
+    startedAt?: number;
+}
+/**
+ * - `queued`: the call is planned but has not started.
+ * - `running`: executing.
+ * - `needs-approval`: waiting for a human decision. Never auto-approved.
+ * - `approved`: a human approved; execution has not reported back yet.
+ * - `denied`: a human refused. Terminal.
+ * - `succeeded` / `failed`: terminal.
+ */
+type ToolState = "queued" | "running" | "needs-approval" | "approved" | "denied" | "succeeded" | "failed";
+/** Details of a human-in-the-loop approval on a tool call. */
+interface ToolApproval {
+    /** Why the call needs approval, shown above the exact action. */
+    prompt?: string;
+    /** The reason the human gave when approving or denying. */
+    reason?: string;
+}
+interface ToolPart {
+    type: "tool";
+    id: string;
+    name: string;
+    state: ToolState;
+    input?: unknown;
+    output?: unknown;
+    /** A human-readable cause when `state` is `failed`. */
+    error?: string;
+    /** A machine-readable cause, such as `aborted` when the user stopped the run. */
+    errorCode?: string;
+    durationMs?: number;
+    /** Epoch milliseconds when the call started. Set by the thread reducer. */
+    startedAt?: number;
+    approval?: ToolApproval;
+}
+interface SourcePart {
+    type: "source";
+    id: string;
+    title: string;
+    url: string;
+    /** Shown in the source list next to the title and domain. */
+    snippet?: string;
+}
+interface FilePart {
+    type: "file";
+    /** Stable id, used by attachment chips. Optional for stored threads. */
+    id?: string;
+    name: string;
+    mediaType: string;
+    url: string;
+    size?: number;
+}
+/** Structured data a component can render, for example an artifact or a chart spec. */
+interface DataPart {
+    type: "data";
+    /** Identifies the shape of `data`, such as `chart` or `diagram`. */
+    kind: string;
+    data: unknown;
+}
+type MessagePart = TextPart | ReasoningPart | ToolPart | SourcePart | FilePart | DataPart;
+type MessagePartType = MessagePart["type"];
+type MessageStatus = "streaming" | "complete" | "error" | "stopped";
+/** Token counts for a response. Providers differ, so every field is optional. */
+interface Usage {
+    inputTokens?: number;
+    outputTokens?: number;
+    totalTokens?: number;
+    reasoningTokens?: number;
+    cachedInputTokens?: number;
+}
+type FinishReason = "stop" | "length" | "tool-calls" | "content-filter" | "error" | "other";
+/**
+ * - `network`: the request never completed (offline, DNS, dropped stream).
+ * - `rate-limit`: the provider asked the client to slow down (HTTP 429).
+ * - `moderation`: the provider refused the content.
+ * - `auth`: missing or rejected credentials.
+ * - `unknown`: anything else.
+ */
+type ErrorKind = "network" | "rate-limit" | "moderation" | "auth" | "unknown";
+interface ThreadError {
+    /** A human-readable cause. Shown as detail under the kind's title. */
+    message: string;
+    kind?: ErrorKind;
+    /** The provider's error code, if any. */
+    code?: string;
+    /** `false` hides the retry action. Defaults to true. */
+    retryable?: boolean;
+}
+interface Message {
+    id: string;
+    role: MessageRole;
+    parts: MessagePart[];
+    status?: MessageStatus;
+    createdAt?: string;
+    /** The message this one replaces or follows, for branches between versions. */
+    parentId?: string;
+    metadata?: Record<string, unknown>;
+    /** Token usage reported when the response finished. */
+    usage?: Usage;
+    finishReason?: FinishReason;
+    /** Set when `status` is `error`. */
+    error?: ThreadError;
+}
+interface Thread {
+    id: string;
+    title?: string;
+    messages: Message[];
+    updatedAt?: string;
+}
+/** Converts a provider's message format into the neutral shape. */
+type MessageAdapter<Input> = (input: Input) => Message;
+/** Converts a provider's whole message list into neutral messages. */
+type MessagesAdapter<Input> = (input: readonly Input[]) => Message[];
+/**
+ * The thread component is stateless. Storage and history belong to the app,
+ * through this small interface.
+ */
+interface ThreadStore {
+    load(threadId: string): Promise<Thread | null>;
+    save(thread: Thread): Promise<void>;
+    list?(): Promise<Array<Pick<Thread, "id" | "title" | "updatedAt">>>;
+    delete?(threadId: string): Promise<void>;
+}
+
+/**
+ * Thread state and its reducer.
+ *
+ * `threadReducer(state, action)` is a pure function: it never mutates `state`
+ * or an action, it returns the same `state` object when an action changes
+ * nothing, and it never reads a clock or generates a random id. Time comes in
+ * through the optional `at` (epoch milliseconds) on actions, and ids come in
+ * through the actions or, when a provider sends none, a deterministic counter.
+ * That makes it safe in React, in tests and in server code.
+ */
+/**
+ * - `idle`: nothing in flight.
+ * - `submitted`: a request was sent and nothing has come back yet.
+ * - `streaming`: an assistant message is being written.
+ * - `error`: the last request failed; `error` has the cause.
+ */
+type ThreadStatus = "idle" | "submitted" | "streaming" | "error";
+/**
+ * Versions of one place in the thread, made by editing a message with
+ * `mode: "branch"`. `alternatives` holds the versions that are not showing,
+ * each one a whole tail of the thread; the showing version is `messages`.
+ */
+interface BranchPoint {
+    /** The message the versions follow, or `""` when the versions start the thread. */
+    parentId: string;
+    /** The versions that are not showing. */
+    alternatives: Message[][];
+    /** Where the showing version sits among all versions, from 0. */
+    activeIndex: number;
+}
+interface ThreadState {
+    /** The messages on the showing path, oldest first. */
+    messages: Message[];
+    status: ThreadStatus;
+    error: ThreadError | null;
+    /** The assistant message being written, or null. */
+    activeMessageId: string | null;
+    /** Branch points by `parentId`. */
+    branches: Record<string, BranchPoint>;
+}
+interface BranchInfo {
+    parentId: string;
+    /** The showing version, from 0. */
+    index: number;
+    /** How many versions exist, including the showing one. */
+    count: number;
+}
+interface ToolCallPatch {
+    name?: string;
+    input?: unknown;
+    output?: unknown;
+    state?: ToolState;
+    error?: string;
+    errorCode?: string;
+    durationMs?: number;
+    approval?: ToolApproval;
+}
+type ThreadAction = 
+/** Replaces the whole thread, for example after loading from a store. */
+{
+    type: "set-messages";
+    messages: Message[];
+}
+/** Adds a ready-made message (system notes, restored history). A duplicate id is ignored. */
+ | {
+    type: "add-message";
+    message: Message;
+} | {
+    type: "add-user-message";
+    id: string;
+    text?: string;
+    attachments?: FilePart[];
+    parts?: MessagePart[];
+    createdAt?: string;
+    /** Defaults to `submitted`: the user message starts a request. */
+    status?: ThreadStatus;
+}
+/** Starts an assistant message. With an existing id it reopens that message. */
+ | {
+    type: "begin-assistant-message";
+    id?: string;
+    createdAt?: string;
+    metadata?: Record<string, unknown>;
+} | {
+    type: "append-text";
+    delta: string;
+    messageId?: string;
+    at?: number;
+} | {
+    type: "append-reasoning";
+    delta: string;
+    messageId?: string;
+    at?: number;
+} | {
+    type: "end-reasoning";
+    messageId?: string;
+    durationMs?: number;
+    at?: number;
+} | {
+    type: "start-tool-call";
+    callId: string;
+    name: string;
+    input?: unknown;
+    state?: ToolState;
+    requiresApproval?: boolean;
+    approvalPrompt?: string;
+    messageId?: string;
+    at?: number;
+} | {
+    type: "update-tool-call";
+    callId: string;
+    patch: ToolCallPatch;
+    messageId?: string;
+    at?: number;
+} | {
+    type: "finish-tool-call";
+    callId: string;
+    name?: string;
+    output?: unknown;
+    error?: string;
+    errorCode?: string;
+    durationMs?: number;
+    messageId?: string;
+    at?: number;
+}
+/** A human decision on a tool call that needs approval. */
+ | {
+    type: "tool-decision";
+    callId: string;
+    decision: "approved" | "denied";
+    reason?: string;
+} | {
+    type: "add-source";
+    source: Omit<SourcePart, "type">;
+    messageId?: string;
+} | {
+    type: "add-part";
+    part: MessagePart;
+    messageId?: string;
+} | {
+    type: "attach-files";
+    files: FilePart[];
+    messageId?: string;
+} | {
+    type: "finish";
+    messageId?: string;
+    usage?: Usage;
+    finishReason?: FinishReason;
+    at?: number;
+} | {
+    type: "error";
+    error: ThreadError | string;
+    messageId?: string;
+    at?: number;
+}
+/** The user stopped the response. Content so far is kept. */
+ | {
+    type: "abort";
+    messageId?: string;
+    at?: number;
+}
+/** Drops the assistant reply to the last user message and gets ready to ask again. */
+ | {
+    type: "regenerate";
+} | {
+    type: "edit-message";
+    messageId: string;
+    text?: string;
+    parts?: MessagePart[];
+    /**
+     * For user messages: `truncate` (default) replaces the message and drops
+     * everything after it; `branch` keeps the old version reachable through
+     * `switch-branch`. Other roles are edited in place.
+     */
+    mode?: "truncate" | "branch";
+    /** Id of the new version in `branch` mode. Defaults to `<id>~<n>`. */
+    newId?: string;
+    createdAt?: string;
+} | {
+    type: "switch-branch";
+    parentId: string;
+    index: number;
+} | {
+    type: "dismiss-error";
+} | {
+    type: "clear";
+} | {
+    type: "batch";
+    actions: ThreadAction[];
+};
+declare function isTerminalToolState(state: ToolState): boolean;
+declare function isBusy(state: Pick<ThreadState, "status">): boolean;
+declare function createThreadState(messages?: readonly Message[]): ThreadState;
+declare function threadReducer(state: ThreadState, action: ThreadAction): ThreadState;
+/** The branch navigator data for a message, if it is where versions fork. */
+declare function getBranchInfo(state: ThreadState, messageId: string): BranchInfo | undefined;
+/** All branch navigator data for the showing messages, by message id. */
+declare function getBranchInfoMap(state: ThreadState): Record<string, BranchInfo>;
+/** The last user message, which is what "regenerate" answers again. */
+declare function lastUserMessage(state: Pick<ThreadState, "messages">): Message | undefined;
+
+/**
+ * Stream events: the one shape every provider is adapted to.
+ *
+ * A provider adapter is an async generator that yields these events. The
+ * thread reducer (`applyStreamEvent`) turns each one into a state change, so
+ * the UI never sees a provider SDK. Unknown event types are ignored, so an
+ * adapter can pass extra events through without breaking older UIs.
+ */
+interface StartEvent {
+    type: "start";
+    /** The assistant message id. Omit it and the hook or reducer makes one. */
+    messageId?: string;
+    createdAt?: string;
+    metadata?: Record<string, unknown>;
+}
+interface TextDeltaEvent {
+    type: "text-delta";
+    delta: string;
+    messageId?: string;
+}
+interface ReasoningDeltaEvent {
+    type: "reasoning-delta";
+    delta: string;
+    messageId?: string;
+}
+/** Ends the open reasoning block. Optional: the first text, tool call or finish also ends it. */
+interface ReasoningEndEvent {
+    type: "reasoning-end";
+    durationMs?: number;
+    messageId?: string;
+}
+interface ToolCallEvent {
+    type: "tool-call";
+    callId: string;
+    name: string;
+    input?: unknown;
+    /** Set when a human has to approve before the tool runs. */
+    requiresApproval?: boolean;
+    /** Why approval is needed. */
+    approvalPrompt?: string;
+    /** Overrides the starting state. Defaults to `running`, or `needs-approval`. */
+    state?: ToolState;
+    messageId?: string;
+}
+interface ToolUpdateEvent {
+    type: "tool-update";
+    callId: string;
+    state?: ToolState;
+    name?: string;
+    input?: unknown;
+    output?: unknown;
+    error?: string;
+    approval?: ToolApproval;
+    messageId?: string;
+}
+interface ToolResultEvent {
+    type: "tool-result";
+    callId: string;
+    output?: unknown;
+    /** Present when the tool failed. */
+    error?: string;
+    durationMs?: number;
+    /** Used only when this result arrives for a call that was never announced. */
+    name?: string;
+    messageId?: string;
+}
+interface SourceEvent {
+    type: "source";
+    id: string;
+    title: string;
+    url: string;
+    snippet?: string;
+    messageId?: string;
+}
+interface FileEvent {
+    type: "file";
+    id?: string;
+    name: string;
+    mediaType: string;
+    url: string;
+    size?: number;
+    messageId?: string;
+}
+interface DataEvent {
+    type: "data";
+    kind: string;
+    data: unknown;
+    messageId?: string;
+}
+interface FinishEvent {
+    type: "finish";
+    usage?: Usage;
+    finishReason?: FinishReason;
+    messageId?: string;
+}
+interface ErrorEvent {
+    type: "error";
+    /** A message, or a full `ThreadError`. */
+    error: string | ThreadError;
+    messageId?: string;
+}
+interface AbortEvent {
+    type: "abort";
+    messageId?: string;
+}
+type StreamEvent = StartEvent | TextDeltaEvent | ReasoningDeltaEvent | ReasoningEndEvent | ToolCallEvent | ToolUpdateEvent | ToolResultEvent | SourceEvent | FileEvent | DataEvent | FinishEvent | ErrorEvent | AbortEvent;
+interface StreamEventOptions {
+    /**
+     * The message to write to when an event names none and no message is being
+     * written. `useThread` sets this to the id it made for the reply.
+     */
+    messageId?: string;
+    /** Epoch milliseconds, for reasoning and tool durations. */
+    at?: number;
+}
+/** Translates one stream event into a reducer action, or null when the event is unknown. */
+declare function streamEventToAction(state: Pick<ThreadState, "activeMessageId">, event: StreamEvent, options?: StreamEventOptions): ThreadAction | null;
+/**
+ * Applies one stream event to the thread state. Content that arrives before a
+ * `start` event starts the assistant message itself, so a provider that never
+ * sends `start` still works.
+ */
+declare function applyStreamEvent(state: ThreadState, event: StreamEvent, options?: StreamEventOptions): ThreadState;
+/** Applies a list of stream events in order. Handy in tests and for replaying a recording. */
+declare function applyStreamEvents(state: ThreadState, events: readonly StreamEvent[], options?: StreamEventOptions): ThreadState;
+/** True for events that end a response, so a consumer can flush pending work. */
+declare function isTerminalStreamEvent(event: StreamEvent): boolean;
+/**
+ * Wraps a stream so it stops when `signal` aborts: iteration ends quietly,
+ * and the source gets `return()` so a generator can clean up (close a socket,
+ * cancel a request). Errors from the source are passed through, except the
+ * abort error itself when the signal is aborted.
+ */
+declare function createAbortableStream<T>(source: AsyncIterable<T>, signal: AbortSignal): AsyncGenerator<T, void, undefined>;
+/** Turns a thrown value into the `error` stream event, so a generator can `catch` and yield it. */
+declare function errorEvent(error: unknown): ErrorEvent;
+
+export { streamEventToAction as $, applyStreamEvent as L, applyStreamEvents as N, createAbortableStream as O, createThreadState as P, errorEvent as Q, getBranchInfo as V, getBranchInfoMap as W, isBusy as X, isTerminalStreamEvent as Y, isTerminalToolState as Z, lastUserMessage as _, threadReducer as a0 };
+export type { AbortEvent as A, BranchInfo as B, ToolApproval as C, DataPart as D, ErrorEvent as E, FilePart as F, ToolCallEvent as G, ToolCallPatch as H, ToolResultEvent as I, ToolState as J, ToolUpdateEvent as K, Message as M, ReasoningDeltaEvent as R, SourcePart as S, ToolPart as T, Usage as U, FinishReason as a, ThreadError as b, BranchPoint as c, DataEvent as d, ErrorKind as e, FileEvent as f, FinishEvent as g, MessageAdapter as h, MessagePart as i, MessagePartType as j, MessageRole as k, MessageStatus as l, MessagesAdapter as m, ReasoningEndEvent as n, ReasoningPart as o, SourceEvent as p, StartEvent as q, StreamEvent as r, StreamEventOptions as s, TextDeltaEvent as t, TextPart as u, Thread as v, ThreadAction as w, ThreadState as x, ThreadStatus as y, ThreadStore as z };