chatkit-bun 0.0.2

package/src/widgets/types.ts

@@ -0,0 +1,52 @@
+import { z } from "zod";
+
+export type WidgetPrimitive = string | number | boolean | null;
+export type WidgetJson = WidgetPrimitive | WidgetJson[] | { [key: string]: WidgetJson | undefined };
+
+export type DynamicWidgetComponent = {
+  type: string;
+  key?: string;
+  id?: string;
+  children?: DynamicWidgetComponent | DynamicWidgetComponent[];
+  [key: string]: WidgetJson | DynamicWidgetComponent | DynamicWidgetComponent[] | undefined;
+};
+
+export type BasicRoot = DynamicWidgetComponent & { type: "Basic" };
+export type DynamicWidgetRoot = DynamicWidgetComponent & { type: "Card" | "ListView" | "Basic" };
+
+export const WidgetJsonSchema: z.ZodType<WidgetJson> = z.lazy(() =>
+  z.union([
+    z.string(),
+    z.number(),
+    z.boolean(),
+    z.null(),
+    z.array(WidgetJsonSchema),
+    z.record(z.string(), z.union([WidgetJsonSchema, z.undefined()])),
+  ]),
+);
+
+export const DynamicWidgetComponentSchema: z.ZodType<DynamicWidgetComponent> = z.lazy(() =>
+  z
+    .object({
+      type: z.string(),
+      key: z.string().optional(),
+      id: z.string().optional(),
+      children: z
+        .union([DynamicWidgetComponentSchema, z.array(DynamicWidgetComponentSchema)])
+        .optional(),
+    })
+    .catchall(WidgetJsonSchema.optional()) as z.ZodType<DynamicWidgetComponent>,
+);
+
+export const BasicRootSchema: z.ZodType<BasicRoot> = DynamicWidgetComponentSchema.refine(
+  (value): value is BasicRoot => value.type === "Basic",
+);
+
+export const DynamicWidgetRootSchema: z.ZodType<DynamicWidgetRoot> =
+  DynamicWidgetComponentSchema.refine(
+    (value): value is DynamicWidgetRoot =>
+      value.type === "Card" || value.type === "ListView" || value.type === "Basic",
+  );
+
+export type WidgetComponent = DynamicWidgetComponent;
+export type WidgetRoot = DynamicWidgetRoot;

package/types/actions.d.ts

@@ -0,0 +1,19 @@
+import { z } from "zod";
+export declare const HandlerSchema: z.ZodUnion<readonly [z.ZodLiteral<"client">, z.ZodLiteral<"server">]>;
+export type Handler = z.infer<typeof HandlerSchema>;
+export declare const LoadingBehaviorSchema: z.ZodUnion<readonly [z.ZodLiteral<"auto">, z.ZodLiteral<"none">, z.ZodLiteral<"self">, z.ZodLiteral<"container">]>;
+export type LoadingBehavior = z.infer<typeof LoadingBehaviorSchema>;
+export declare const ActionConfigSchema: z.ZodObject<{
+    type: z.ZodString;
+    payload: z.ZodOptional<z.ZodUnknown>;
+    handler: z.ZodDefault<z.ZodUnion<readonly [z.ZodLiteral<"client">, z.ZodLiteral<"server">]>>;
+    loadingBehavior: z.ZodDefault<z.ZodUnion<readonly [z.ZodLiteral<"auto">, z.ZodLiteral<"none">, z.ZodLiteral<"self">, z.ZodLiteral<"container">]>>;
+    streaming: z.ZodDefault<z.ZodBoolean>;
+}, z.core.$strip>;
+export type ActionConfig = z.infer<typeof ActionConfigSchema>;
+export interface CreateActionOptions {
+    handler?: Handler;
+    loadingBehavior?: LoadingBehavior;
+    streaming?: boolean;
+}
+export declare function createActionConfig(type: string, payload?: unknown, options?: CreateActionOptions): ActionConfig;

package/types/agents/accumulate.d.ts

@@ -0,0 +1,4 @@
+import type { MarkdownWidget, TextWidget } from "../widgets";
+type AccumulatableTextWidget = TextWidget | MarkdownWidget;
+export type { AccumulatableTextWidget };
+export declare function accumulateText<TWidget extends AccumulatableTextWidget>(events: AsyncIterable<unknown>, baseWidget: TWidget): AsyncGenerator<TWidget, void, unknown>;

package/types/agents/annotations.d.ts

@@ -0,0 +1,21 @@
+import type { Annotation } from "../types/core";
+export interface ResponseStreamConverterOptions {
+    partialImages?: number | null;
+}
+export declare class ResponseStreamConverter {
+    private readonly partialImages;
+    constructor(options?: ResponseStreamConverterOptions);
+    base64ImageToUrl(_imageId: string, base64Image: string, _partialImageIndex?: number | null): string | Promise<string>;
+    partialImageIndexToProgress(partialImageIndex: number): number;
+    convertAnnotation(annotation: unknown): Annotation | null;
+    fileCitationToAnnotation(annotation: unknown): Annotation | null;
+    containerFileCitationToAnnotation(annotation: unknown): Annotation | null;
+    urlCitationToAnnotation(annotation: unknown): Annotation | null;
+}
+export interface ConvertedTextContent {
+    type: "output_text";
+    text: string;
+    annotations: Annotation[];
+}
+export declare function convertTextContentPart(part: unknown, converter: ResponseStreamConverter): ConvertedTextContent | null;
+export declare const defaultResponseStreamConverter: ResponseStreamConverter;

package/types/agents/context.d.ts

@@ -0,0 +1,35 @@
+import type { Task, ThreadItem, Workflow, WorkflowSummary } from "../types/core";
+import { type ThreadStreamEvent } from "../types/server";
+import { type WidgetRoot } from "../widgets";
+import type { AgentContextOptions, JsonObject } from "./types";
+export declare class ClientToolCall {
+    readonly name: string;
+    readonly arguments: JsonObject;
+    constructor(name: string, args?: JsonObject);
+}
+type WorkflowItem = Extract<ThreadItem, {
+    type: "workflow";
+}>;
+export declare class AgentContext<TContext> {
+    readonly thread: AgentContextOptions<TContext>["thread"];
+    readonly store: AgentContextOptions<TContext>["store"];
+    readonly context: TContext;
+    readonly previousResponseId: string | null;
+    workflowItem: WorkflowItem | null;
+    private readonly now;
+    private readonly queue;
+    private clientToolCall;
+    constructor(options: AgentContextOptions<TContext>);
+    stream(event: ThreadStreamEvent): void;
+    streamWidget(widget: WidgetRoot | AsyncIterable<WidgetRoot>, copyText?: string | null): Promise<void>;
+    events(): AsyncIterable<ThreadStreamEvent>;
+    closeEvents(): void;
+    startWorkflow(workflow: Workflow): void;
+    addWorkflowTask(task: Task): void;
+    updateWorkflowTask(task: Task, taskIndex: number): void;
+    endWorkflow(summary?: WorkflowSummary, expanded?: boolean): void;
+    setClientToolCall(toolCall: ClientToolCall): void;
+    getClientToolCall(): ClientToolCall | null;
+    createdAt(): string;
+}
+export {};

package/types/agents/converter.d.ts

@@ -0,0 +1,60 @@
+import type { AgentInputItem } from "@openai/agents";
+import type { Attachment, ThreadItem, UserMessageContent } from "../types/core";
+export type UserMessageItem = Extract<ThreadItem, {
+    type: "user_message";
+}>;
+export type AssistantMessageItem = Extract<ThreadItem, {
+    type: "assistant_message";
+}>;
+export type ClientToolCallItem = Extract<ThreadItem, {
+    type: "client_tool_call";
+}>;
+export type WidgetItem = Extract<ThreadItem, {
+    type: "widget";
+}>;
+export type GeneratedImageItem = Extract<ThreadItem, {
+    type: "generated_image";
+}>;
+export type StructuredInputItem = Extract<ThreadItem, {
+    type: "structured_input";
+}>;
+export type TaskItem = Extract<ThreadItem, {
+    type: "task";
+}>;
+export type WorkflowItem = Extract<ThreadItem, {
+    type: "workflow";
+}>;
+export type HiddenContextItem = Extract<ThreadItem, {
+    type: "hidden_context_item";
+}>;
+export type SDKHiddenContextItem = Extract<ThreadItem, {
+    type: "sdk_hidden_context";
+}>;
+export type EndOfTurnItem = Extract<ThreadItem, {
+    type: "end_of_turn";
+}>;
+export type UserMessageTagContent = Extract<UserMessageContent, {
+    type: "input_tag";
+}>;
+export type AgentUserMessageItem = Extract<AgentInputItem, {
+    role: "user";
+}>;
+export type AgentMessageContentPart = Exclude<AgentUserMessageItem["content"], string>[number];
+export type ThreadItemConverterResult = AgentInputItem | AgentInputItem[] | null | undefined;
+export declare class ThreadItemConverter {
+    attachmentToMessageContent(_attachment: Attachment): AgentMessageContentPart | Promise<AgentMessageContentPart>;
+    tagToMessageContent(_tag: UserMessageTagContent): AgentMessageContentPart | Promise<AgentMessageContentPart>;
+    generatedImageToInput(item: GeneratedImageItem): ThreadItemConverterResult | Promise<ThreadItemConverterResult>;
+    hiddenContextToInput(item: HiddenContextItem): ThreadItemConverterResult | Promise<ThreadItemConverterResult>;
+    sdkHiddenContextToInput(item: SDKHiddenContextItem): ThreadItemConverterResult | Promise<ThreadItemConverterResult>;
+    taskToInput(item: TaskItem): ThreadItemConverterResult | Promise<ThreadItemConverterResult>;
+    workflowToInput(item: WorkflowItem): ThreadItemConverterResult | Promise<ThreadItemConverterResult>;
+    widgetToInput(item: WidgetItem): Promise<ThreadItemConverterResult>;
+    structuredInputToInput(item: StructuredInputItem): ThreadItemConverterResult | Promise<ThreadItemConverterResult>;
+    userMessageToInput(item: UserMessageItem, isLastMessage?: boolean): Promise<ThreadItemConverterResult>;
+    assistantMessageToInput(item: AssistantMessageItem): ThreadItemConverterResult | Promise<ThreadItemConverterResult>;
+    clientToolCallToInput(item: ClientToolCallItem): ThreadItemConverterResult | Promise<ThreadItemConverterResult>;
+    endOfTurnToInput(_item: EndOfTurnItem): ThreadItemConverterResult | Promise<ThreadItemConverterResult>;
+    toAgentInput(threadItems: ThreadItem | readonly ThreadItem[]): Promise<AgentInputItem[]>;
+}
+export declare function simpleToAgentInput(threadItems: ThreadItem | readonly ThreadItem[]): Promise<AgentInputItem[]>;

package/types/agents/index.d.ts

@@ -0,0 +1,9 @@
+export { ResponseStreamConverter, defaultResponseStreamConverter } from "./annotations";
+export type { ResponseStreamConverterOptions } from "./annotations";
+export { accumulateText } from "./accumulate";
+export type { AccumulatableTextWidget } from "./accumulate";
+export { ThreadItemConverter, simpleToAgentInput } from "./converter";
+export type { AgentMessageContentPart, AgentUserMessageItem, AssistantMessageItem, ClientToolCallItem, EndOfTurnItem, GeneratedImageItem, HiddenContextItem, SDKHiddenContextItem, StructuredInputItem, TaskItem, ThreadItemConverterResult, UserMessageItem, UserMessageTagContent, WidgetItem, WorkflowItem, } from "./converter";
+export { AgentContext, ClientToolCall } from "./context";
+export { streamAgentResponse } from "./stream";
+export type { AgentContextOptions, AgentStreamInput, StreamAgentResponseOptions } from "./types";

package/types/agents/stream.d.ts

@@ -0,0 +1,4 @@
+import { type ThreadStreamEvent } from "../types/server";
+import type { AgentContext } from "./context";
+import type { AgentStreamInput, StreamAgentResponseOptions } from "./types";
+export declare function streamAgentResponse<TContext>(context: AgentContext<TContext>, streamedRun: AgentStreamInput | AsyncIterable<unknown>, options?: StreamAgentResponseOptions): AsyncIterable<ThreadStreamEvent>;

package/types/agents/types.d.ts

@@ -0,0 +1,26 @@
+import type { Store } from "../store";
+import type { JsonValue } from "../serialization";
+import type { ThreadMetadata } from "../types/core";
+import type { ResponseStreamConverter } from "./annotations";
+export interface AgentContextOptions<TContext> {
+    thread: ThreadMetadata;
+    store: Store<TContext>;
+    context: TContext;
+    previousResponseId?: string | null;
+    now?: () => Date | string;
+}
+export interface AgentStreamInput {
+    [Symbol.asyncIterator]?: () => AsyncIterator<unknown>;
+    toStream?: () => AsyncIterable<unknown>;
+}
+export interface StreamAgentResponseOptions {
+    converter?: ResponseStreamConverter;
+}
+export interface ToolCallMetadata {
+    itemId: string | null;
+    callId: string | null;
+}
+export type { JsonValue } from "../serialization";
+export type JsonObject = {
+    [key: string]: JsonValue;
+};

package/types/agents/workflows.d.ts

@@ -0,0 +1,34 @@
+import { type Task, type ThreadItem, type Workflow, type WorkflowSummary } from "../types/core";
+import type { ThreadStreamEvent } from "../types/server";
+import type { AgentContext } from "./context";
+export type WorkflowItem = Extract<ThreadItem, {
+    type: "workflow";
+}>;
+export type ThoughtTask = Extract<WorkflowItem["workflow"]["tasks"][number], {
+    type: "thought";
+}>;
+export type ThreadItemAddedEvent = Extract<ThreadStreamEvent, {
+    type: "thread.item.added";
+}>;
+export type ThreadItemDoneEvent = Extract<ThreadStreamEvent, {
+    type: "thread.item.done";
+}>;
+export type ThreadItemUpdatedEvent = Extract<ThreadStreamEvent, {
+    type: "thread.item.updated";
+}>;
+export declare function isWorkflowItem(item: ThreadItem | undefined): item is WorkflowItem;
+export declare function createWorkflowItem<TContext>(context: AgentContext<TContext>, workflow: Workflow): WorkflowItem;
+export declare function createReasoningWorkflowItem<TContext>(context: AgentContext<TContext>): WorkflowItem;
+export declare function shouldEmitWorkflowAdded(workflow: Workflow): boolean;
+export declare function workflowAddedEvent(workflow: WorkflowItem): ThreadItemAddedEvent;
+export declare function resumeWorkflowFromThreadItems<TContext>(context: AgentContext<TContext>, items: readonly ThreadItem[]): void;
+export declare function shouldAutoEndWorkflowForItem<TContext>(context: AgentContext<TContext>, item: ThreadItem): boolean;
+export declare function createThoughtTask(content: string): ThoughtTask;
+export declare function workflowTaskAddedEvent(workflow: WorkflowItem, task: Task, taskIndex: number): ThreadItemUpdatedEvent;
+export declare function workflowTaskUpdatedEvent(workflow: WorkflowItem, task: Task, taskIndex: number): ThreadItemUpdatedEvent;
+export declare function normalizeWorkflowTask(task: Task): Task;
+export declare function appendWorkflowTask(workflow: WorkflowItem, task: Task): ThreadItemUpdatedEvent;
+export declare function updateWorkflowTaskEvent(workflow: WorkflowItem, task: Task, taskIndex: number): ThreadItemUpdatedEvent;
+export declare function durationSeconds(startedAt: string, endedAt: string): number;
+export declare function finishWorkflow<TContext>(context: AgentContext<TContext>, summary?: WorkflowSummary, expanded?: boolean): ThreadItemDoneEvent | null;
+export declare function persistOpenWorkflow<TContext>(context: AgentContext<TContext>): Promise<void>;

package/types/errors.d.ts

@@ -0,0 +1,11 @@
+export declare class ChatKitError extends Error {
+    constructor(message: string);
+}
+export declare class NotFoundError extends ChatKitError {
+}
+export declare class UnsupportedOperationError extends ChatKitError {
+}
+export declare class ValidationError extends ChatKitError {
+    readonly cause?: unknown | undefined;
+    constructor(message: string, cause?: unknown | undefined);
+}

package/types/http.d.ts

@@ -0,0 +1,6 @@
+import { type ChatKitServer } from "./server";
+export interface ChatKitHandlerOptions<TContext> {
+    getContext?: (request: Request) => TContext | Promise<TContext>;
+}
+export type ChatKitHandler = (request: Request) => Promise<Response>;
+export declare function createChatKitHandler<TContext = undefined>(server: ChatKitServer<TContext>, options?: ChatKitHandlerOptions<TContext>): ChatKitHandler;

package/types/index.d.ts

@@ -0,0 +1,11 @@
+export * from "./actions";
+export * from "./agents";
+export * from "./errors";
+export * from "./http";
+export * from "./serialization";
+export * from "./server";
+export * from "./sqlite-store";
+export * from "./store";
+export * from "./types/core";
+export * from "./types/server";
+export * from "./widgets";

package/types/serialization.d.ts

@@ -0,0 +1,8 @@
+export type JsonValue = string | number | boolean | null | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+export declare function encodeJsonBytes(value: unknown): Uint8Array;
+export declare function decodeJsonBytes(input: string | Uint8Array | ArrayBuffer): unknown;
+export declare function omitUndefinedDeep(value: unknown): unknown;
+export declare function parseDate(value: string | Date): Date;
+export declare function serializeDate(value: string | Date): string;

package/types/server.d.ts

@@ -0,0 +1,73 @@
+import type { AttachmentStore, Store } from "./store";
+import { type ThreadItem, type ThreadMetadata } from "./types/core";
+import { type AudioInput, type FeedbackKind, type NonStreamingRequest, type StreamOptions, type StreamingRequest, type StructuredInputSubmission, type SyncCustomActionResponse, type Thread, type ThreadCustomActionParams, type ThreadItemUpdate, type ThreadStreamEvent, type TranscriptionResult, type UserMessageInput } from "./types/server";
+type UserMessageItem = Extract<ThreadItem, {
+    type: "user_message";
+}>;
+type AssistantMessageItem = Extract<ThreadItem, {
+    type: "assistant_message";
+}>;
+type StructuredInputItem = Extract<ThreadItem, {
+    type: "structured_input";
+}>;
+type WidgetItem = Extract<ThreadItem, {
+    type: "widget";
+}>;
+type ProcessRequestInput = string | Uint8Array | ArrayBuffer;
+export declare class StreamingResult implements AsyncIterable<Uint8Array> {
+    readonly jsonEvents: AsyncIterable<Uint8Array>;
+    constructor(jsonEvents: AsyncIterable<Uint8Array>);
+    [Symbol.asyncIterator](): AsyncIterator<Uint8Array>;
+}
+export declare class NonStreamingResult {
+    readonly json: Uint8Array;
+    constructor(json: Uint8Array);
+}
+export declare class StreamCancelledError extends Error {
+    constructor(message?: string);
+}
+export declare abstract class ChatKitServer<TContext = unknown> {
+    readonly store: Store<TContext>;
+    readonly attachmentStore: AttachmentStore<TContext> | null;
+    constructor(store: Store<TContext>, attachmentStore?: AttachmentStore<TContext> | null);
+    abstract respond(thread: ThreadMetadata, inputUserMessage: UserMessageItem | null, context: TContext): AsyncIterable<ThreadStreamEvent>;
+    addFeedback(_threadId: string, _itemIds: string[], _kind: FeedbackKind, _context: TContext): Promise<void>;
+    transcribe(_audio: AudioInput, _context: TContext): Promise<TranscriptionResult>;
+    action(_thread: ThreadMetadata, _action: ThreadCustomActionParams["action"], _sender: WidgetItem | null, _context: TContext): AsyncIterable<ThreadStreamEvent>;
+    syncAction(_thread: ThreadMetadata, _action: ThreadCustomActionParams["action"], _sender: WidgetItem | null, _context: TContext): Promise<SyncCustomActionResponse>;
+    getStreamOptions(_thread: ThreadMetadata, _context: TContext): StreamOptions;
+    handleStreamCancelled(thread: ThreadMetadata, pendingItems: ThreadItem[], context: TContext): Promise<void>;
+    process(request: ProcessRequestInput, context: TContext): Promise<StreamingResult | NonStreamingResult>;
+    protected processNonStreaming(request: NonStreamingRequest, context: TContext): Promise<Uint8Array>;
+    protected processStreaming(request: StreamingRequest, context: TContext): AsyncIterable<Uint8Array>;
+    protected processStreamingImpl(request: StreamingRequest, context: TContext): AsyncIterable<ThreadStreamEvent>;
+    protected buildUserMessageItem(input: UserMessageInput, thread: ThreadMetadata, context: TContext): Promise<UserMessageItem>;
+    protected processNewThreadItemRespond(thread: ThreadMetadata, item: UserMessageItem, context: TContext): AsyncIterable<ThreadStreamEvent>;
+    protected persistUserMessageItem(thread: ThreadMetadata, item: UserMessageItem, context: TContext): Promise<void>;
+    protected processStreamingContinuation(request: Exclude<StreamingRequest, {
+        type: "threads.create" | "threads.add_user_message";
+    }>, context: TContext): AsyncIterable<ThreadStreamEvent>;
+    protected loadThreadItemsDescending(thread: ThreadMetadata, context: TContext): AsyncIterable<ThreadItem>;
+    protected cleanupPendingClientToolCall(thread: ThreadMetadata, context: TContext): Promise<void>;
+    protected applyStructuredInputSubmission(item: StructuredInputItem, submission: StructuredInputSubmission): StructuredInputItem;
+    protected removeItemsAfterUserMessage(thread: ThreadMetadata, itemId: string, context: TContext): Promise<UserMessageItem>;
+    protected processEvents(thread: ThreadMetadata, context: TContext, stream: () => AsyncIterable<ThreadStreamEvent>): AsyncIterable<ThreadStreamEvent>;
+    protected updatePendingItems(pendingItems: Map<string, ThreadItem>, itemId: string, update: ThreadItemUpdate): boolean;
+    protected mergePendingUpdatesIntoDoneItem(doneItem: ThreadItem, pendingItem: ThreadItem | undefined, hasPendingUpdates: boolean): ThreadItem;
+    private mergeAssistantMessageContent;
+    protected applyAssistantMessageUpdate(item: AssistantMessageItem, update: Extract<ThreadItemUpdate, {
+        type: `assistant_message.${string}`;
+    }>): AssistantMessageItem;
+    private hasThreadChanged;
+    protected serialize(value: unknown): Uint8Array;
+    private getAttachmentStore;
+    protected loadFullThread(threadId: string, context: TContext): Promise<Thread>;
+    protected toThreadResponse(thread: ThreadMetadata | Thread): Thread;
+    protected isHiddenItem(item: ThreadItem): boolean;
+    private isKnownHiddenItem;
+    private isStoredHiddenItem;
+    protected processSyncCustomAction(request: Extract<NonStreamingRequest, {
+        type: "threads.sync_custom_action";
+    }>, context: TContext): Promise<SyncCustomActionResponse>;
+}
+export {};

package/types/sqlite-store.d.ts

@@ -0,0 +1,43 @@
+import { BaseStore } from "./store";
+import { type Attachment, type Page, type ThreadItem, type ThreadMetadata } from "./types/core";
+export interface SQLiteStoreOptions<TContext> {
+    path?: string;
+    getUserId(context: TContext): string;
+}
+export declare class SQLiteStore<TContext = unknown> extends BaseStore<TContext> {
+    private readonly db;
+    private readonly getUserId;
+    constructor(options: SQLiteStoreOptions<TContext>);
+    close(): void;
+    loadThread(threadId: string, context: TContext): Promise<ThreadMetadata>;
+    saveThread(thread: ThreadMetadata, context: TContext): Promise<void>;
+    loadThreads(limit: number, after: string | null, order: "asc" | "desc", context: TContext): Promise<Page<ThreadMetadata>>;
+    addThreadItem(threadId: string, item: ThreadItem, context: TContext): Promise<void>;
+    saveItem(threadId: string, item: ThreadItem, context: TContext): Promise<void>;
+    loadItem(threadId: string, itemId: string, context: TContext): Promise<ThreadItem>;
+    loadThreadItems(threadId: string, after: string | null, limit: number, order: "asc" | "desc", context: TContext): Promise<Page<ThreadItem>>;
+    deleteThread(threadId: string, context: TContext): Promise<void>;
+    deleteThreadItem(threadId: string, itemId: string, context: TContext): Promise<void>;
+    saveAttachment(attachment: Attachment, context: TContext): Promise<void>;
+    loadAttachment(attachmentId: string, context: TContext): Promise<Attachment>;
+    deleteAttachment(attachmentId: string, context: TContext): Promise<void>;
+    private createSchema;
+    private userId;
+    private threadRow;
+    private itemRow;
+    private attachmentRow;
+    private threadCursor;
+    private itemCursor;
+    private threadRows;
+    private threadRowsAfter;
+    private itemRows;
+    private itemRowsAfter;
+    private page;
+    private requestedLimit;
+    private assertPositiveLimit;
+    private queryLimit;
+    private orderSql;
+    private parseThread;
+    private parseItem;
+    private parseAttachment;
+}

package/types/store.d.ts

@@ -0,0 +1,45 @@
+import type { Attachment, Page, ThreadItem, ThreadMetadata } from "./types/core";
+export type StoreItemType = "thread" | "message" | "tool_call" | "task" | "workflow" | "attachment" | "sdk_hidden_context";
+export declare function defaultGenerateId(itemType: StoreItemType): string;
+export interface AttachmentCreateParams {
+    name: string;
+    size: number;
+    mime_type: string;
+}
+export interface AttachmentStore<TContext = unknown> {
+    deleteAttachment(attachmentId: string, context: TContext): Promise<void>;
+    createAttachment(input: AttachmentCreateParams, context: TContext): Promise<Attachment>;
+    generateAttachmentId?(mimeType: string, context: TContext): string;
+}
+export interface Store<TContext = unknown> {
+    generateThreadId(context: TContext): string;
+    generateItemId(itemType: StoreItemType, thread: ThreadMetadata, context: TContext): string;
+    loadThread(threadId: string, context: TContext): Promise<ThreadMetadata>;
+    saveThread(thread: ThreadMetadata, context: TContext): Promise<void>;
+    loadThreadItems(threadId: string, after: string | null, limit: number, order: "asc" | "desc", context: TContext): Promise<Page<ThreadItem>>;
+    saveAttachment(attachment: Attachment, context: TContext): Promise<void>;
+    loadAttachment(attachmentId: string, context: TContext): Promise<Attachment>;
+    deleteAttachment(attachmentId: string, context: TContext): Promise<void>;
+    loadThreads(limit: number, after: string | null, order: "asc" | "desc", context: TContext): Promise<Page<ThreadMetadata>>;
+    addThreadItem(threadId: string, item: ThreadItem, context: TContext): Promise<void>;
+    saveItem(threadId: string, item: ThreadItem, context: TContext): Promise<void>;
+    loadItem(threadId: string, itemId: string, context: TContext): Promise<ThreadItem>;
+    deleteThread(threadId: string, context: TContext): Promise<void>;
+    deleteThreadItem(threadId: string, itemId: string, context: TContext): Promise<void>;
+}
+export declare abstract class BaseStore<TContext = unknown> implements Store<TContext> {
+    generateThreadId(_context: TContext): string;
+    generateItemId(itemType: StoreItemType, _thread: ThreadMetadata, _context: TContext): string;
+    abstract loadThread(threadId: string, context: TContext): Promise<ThreadMetadata>;
+    abstract saveThread(thread: ThreadMetadata, context: TContext): Promise<void>;
+    abstract loadThreadItems(threadId: string, after: string | null, limit: number, order: "asc" | "desc", context: TContext): Promise<Page<ThreadItem>>;
+    abstract saveAttachment(attachment: Attachment, context: TContext): Promise<void>;
+    abstract loadAttachment(attachmentId: string, context: TContext): Promise<Attachment>;
+    abstract deleteAttachment(attachmentId: string, context: TContext): Promise<void>;
+    abstract loadThreads(limit: number, after: string | null, order: "asc" | "desc", context: TContext): Promise<Page<ThreadMetadata>>;
+    abstract addThreadItem(threadId: string, item: ThreadItem, context: TContext): Promise<void>;
+    abstract saveItem(threadId: string, item: ThreadItem, context: TContext): Promise<void>;
+    abstract loadItem(threadId: string, itemId: string, context: TContext): Promise<ThreadItem>;
+    abstract deleteThread(threadId: string, context: TContext): Promise<void>;
+    abstract deleteThreadItem(threadId: string, itemId: string, context: TContext): Promise<void>;
+}