chatkit-bun 0.0.2

package/README.md

@@ -0,0 +1,202 @@
+# chatkit-bun
+
+`chatkit-bun` is a Bun-native server bridge for ChatKit-style thread APIs. It includes:
+
+- ChatKit request processing and SSE response helpers.
+- SQLite-backed thread and item storage.
+- Widget serialization and streaming helpers.
+- `@openai/agents` stream conversion helpers for Bun servers.
+
+## Development
+
+Install dependencies:
+
+```bash
+bun install
+```
+
+Run typecheck and tests:
+
+```bash
+bun run verify
+```
+
+The package is source-distributed for Bun apps. Its package entrypoint is `src/index.ts`, so a private Git install does not need a build step or committed `dist` output.
+
+Install from a private GitHub URL in a Bun app:
+
+```json
+{
+  "dependencies": {
+    "@openai/agents": "^0.11.6",
+    "chatkit-bun": "git+ssh://git@github.com/ottersoft-x/chatkit-bun.git#main"
+  }
+}
+```
+
+## Bun Agent Server Example
+
+Use `ChatKitServer` to bridge ChatKit requests to an `@openai/agents` workflow. This example streams an intake agent first, passes its summary to an isolated research agent that does not receive the prior chat history, then passes both outputs to the final answer agent. Each stage emits workflow updates so the frontend can show what is happening:
+
+```ts
+import { Agent, run } from "@openai/agents";
+import {
+  AgentContext,
+  ChatKitServer,
+  SQLiteStore,
+  createChatKitHandler,
+  simpleToAgentInput,
+  streamAgentResponse,
+  type ThreadItem,
+  type ThreadMetadata,
+  type ThreadStreamEvent,
+} from "chatkit-bun";
+
+interface RequestContext {
+  userId: string;
+}
+
+type UserMessageItem = Extract<ThreadItem, { type: "user_message" }>;
+
+const intakeAgent = new Agent({
+  name: "Intake Agent",
+  instructions:
+    "Read the conversation and summarize the user's goal, constraints, and any missing context.",
+});
+
+const answerAgent = new Agent({
+  name: "Answer Agent",
+  instructions:
+    "Use the intake summary and research notes to produce a concise, helpful final answer for the user.",
+});
+
+const researchAgent = new Agent({
+  name: "Research Agent",
+  instructions:
+    "You receive only a task summary, not the conversation history. Return focused research notes.",
+});
+
+function requestContext(request: Request): RequestContext {
+  return {
+    userId: request.headers.get("x-user-id") ?? "anonymous",
+  };
+}
+
+function threadPreviousResponseId(thread: ThreadMetadata): string | null {
+  const value = thread.metadata.previous_response_id;
+  return typeof value === "string" ? value : null;
+}
+
+class AppChatKitServer extends ChatKitServer<RequestContext> {
+  constructor(readonly sqlitePath = Bun.env.CHATKIT_SQLITE_PATH ?? "chatkit.sqlite") {
+    super(
+      new SQLiteStore<RequestContext>({
+        path: sqlitePath,
+        getUserId: (context) => context.userId,
+      }),
+    );
+  }
+
+  override async *respond(
+    thread: ThreadMetadata,
+    _inputUserMessage: UserMessageItem | null,
+    context: RequestContext,
+  ): AsyncIterable<ThreadStreamEvent> {
+    const page = await this.store.loadThreadItems(thread.id, null, 50, "asc", context);
+    const input = await simpleToAgentInput(page.data);
+    const previousResponseId = threadPreviousResponseId(thread);
+
+    const intakeContext = new AgentContext({
+      thread,
+      store: this.store,
+      context,
+      previousResponseId,
+    });
+    intakeContext.addWorkflowTask({
+      type: "custom",
+      title: "Reviewing the request",
+      content: "The intake agent is identifying the user's goal and constraints.",
+      status_indicator: "loading",
+    });
+
+    const intakeRun = await run(intakeAgent, input, {
+      stream: true,
+      previousResponseId: previousResponseId ?? undefined,
+    });
+
+    yield* streamAgentResponse(intakeContext, intakeRun);
+    await intakeRun.completed;
+
+    const intakeSummary = String(intakeRun.finalOutput ?? "No intake summary was produced.");
+    const researchContext = new AgentContext({
+      thread,
+      store: this.store,
+      context,
+    });
+    researchContext.addWorkflowTask({
+      type: "custom",
+      title: "Checking isolated context",
+      content: "The research agent is working from the intake summary only.",
+      status_indicator: "loading",
+    });
+
+    const researchRun = await run(
+      researchAgent,
+      `Research this request using only this summary:\n\n${intakeSummary}`,
+      { stream: true },
+    );
+
+    yield* streamAgentResponse(researchContext, researchRun);
+    await researchRun.completed;
+
+    const researchNotes = String(researchRun.finalOutput ?? "No research notes were produced.");
+    const answerContext = new AgentContext({
+      thread,
+      store: this.store,
+      context,
+      previousResponseId: intakeRun.lastResponseId ?? previousResponseId,
+    });
+    answerContext.addWorkflowTask({
+      type: "custom",
+      title: "Drafting the answer",
+      content: "The answer agent is combining the intake summary and isolated research notes.",
+      status_indicator: "loading",
+    });
+
+    const answerRun = await run(
+      answerAgent,
+      `Use this intake summary and research notes.
+
+Intake summary:
+${intakeSummary}
+
+Research notes:
+${researchNotes}`,
+      {
+        stream: true,
+        previousResponseId: answerContext.previousResponseId ?? undefined,
+      },
+    );
+
+    yield* streamAgentResponse(answerContext, answerRun);
+  }
+}
+
+const chatkitHandler = createChatKitHandler(new AppChatKitServer(), {
+  getContext: requestContext,
+});
+
+const server = Bun.serve({
+  port: Number(Bun.env.PORT ?? 3000),
+  routes: {
+    "/health": new Response("ok"),
+    "/chatkit": {
+      POST: chatkitHandler,
+    },
+  },
+});
+
+console.log(`ChatKit server listening on ${server.url}`);
+```
+
+The server listens on `PORT` or `3000` and exposes `POST /chatkit`. It uses `x-user-id` as the per-request user id, falling back to `anonymous`.

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "chatkit-bun",
+  "version": "0.0.2",
+  "module": "./src/index.ts",
+  "types": "./types/index.d.ts",
+  "type": "module",
+  "files": [
+    "src",
+    "types"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": {
+      "types": "./types/index.d.ts",
+      "import": "./src/index.ts"
+    }
+  },
+  "devDependencies": {
+    "@types/bun": "^1.3.14",
+    "@types/nunjucks": "^3.2.6",
+    "typescript": "^6.0.3"
+  },
+  "peerDependencies": {
+    "typescript": "^6"
+  },
+  "dependencies": {
+    "@openai/agents": "^0.11.5",
+    "nunjucks": "^3.2.4",
+    "zod": "^4.4.3"
+  },
+  "scripts": {
+    "test": "bun test",
+    "build:types": "bunx tsc -p tsconfig.types.json",
+    "typecheck": "bunx tsc --noEmit",
+    "verify": "bun run typecheck && bun test",
+    "verify:parity": "bun run verify && bun scripts/verify-parity.ts"
+  }
+}

package/src/actions.ts

@@ -0,0 +1,39 @@
+import { z } from "zod";
+
+export const HandlerSchema = z.union([z.literal("client"), z.literal("server")]);
+export type Handler = z.infer<typeof HandlerSchema>;
+
+export const LoadingBehaviorSchema = z.union([
+  z.literal("auto"),
+  z.literal("none"),
+  z.literal("self"),
+  z.literal("container"),
+]);
+export type LoadingBehavior = z.infer<typeof LoadingBehaviorSchema>;
+
+export const ActionConfigSchema = z.object({
+  type: z.string(),
+  payload: z.unknown().optional(),
+  handler: HandlerSchema.default("server"),
+  loadingBehavior: LoadingBehaviorSchema.default("auto"),
+  streaming: z.boolean().default(true),
+});
+export type ActionConfig = z.infer<typeof ActionConfigSchema>;
+
+export interface CreateActionOptions {
+  handler?: Handler;
+  loadingBehavior?: LoadingBehavior;
+  streaming?: boolean;
+}
+
+export function createActionConfig(
+  type: string,
+  payload?: unknown,
+  options: CreateActionOptions = {},
+): ActionConfig {
+  return ActionConfigSchema.parse({
+    type,
+    payload,
+    ...options,
+  });
+}

package/src/agents/accumulate.ts

@@ -0,0 +1,43 @@
+import type { MarkdownWidget, TextWidget } from "../widgets";
+
+type AccumulatableTextWidget = TextWidget | MarkdownWidget;
+type UnknownRecord = Record<string, unknown>;
+
+function isRecord(value: unknown): value is UnknownRecord {
+  return typeof value === "object" && value !== null;
+}
+
+function outputTextDelta(event: unknown): string | null {
+  if (!isRecord(event) || event.type !== "raw_response_event" || !isRecord(event.data)) {
+    return null;
+  }
+
+  if (event.data.type !== "response.output_text.delta") {
+    return null;
+  }
+
+  return typeof event.data.delta === "string" ? event.data.delta : null;
+}
+
+export type { AccumulatableTextWidget };
+
+export async function* accumulateText<TWidget extends AccumulatableTextWidget>(
+  events: AsyncIterable<unknown>,
+  baseWidget: TWidget,
+): AsyncGenerator<TWidget, void, unknown> {
+  let text = "";
+
+  yield baseWidget;
+
+  for await (const event of events) {
+    const delta = outputTextDelta(event);
+    if (delta === null) {
+      continue;
+    }
+
+    text += delta;
+    yield { ...baseWidget, value: text } as TWidget;
+  }
+
+  yield { ...baseWidget, value: text, streaming: false } as TWidget;
+}

package/src/agents/annotations.ts

@@ -0,0 +1,157 @@
+import type { Annotation } from "../types/core";
+
+type UnknownRecord = Record<string, unknown>;
+
+function isRecord(value: unknown): value is UnknownRecord {
+  return typeof value === "object" && value !== null;
+}
+
+function stringValue(value: unknown): string | null {
+  return typeof value === "string" ? value : null;
+}
+
+function nonEmptyStringValue(value: unknown): string | null {
+  const text = stringValue(value);
+  return text && text.length > 0 ? text : null;
+}
+
+function numberValue(value: unknown): number | null {
+  return typeof value === "number" && Number.isInteger(value) ? value : null;
+}
+
+export interface ResponseStreamConverterOptions {
+  partialImages?: number | null;
+}
+
+export class ResponseStreamConverter {
+  private readonly partialImages: number | null;
+
+  constructor(options: ResponseStreamConverterOptions = {}) {
+    this.partialImages = options.partialImages ?? null;
+  }
+
+  base64ImageToUrl(
+    _imageId: string,
+    base64Image: string,
+    _partialImageIndex: number | null = null,
+  ): string | Promise<string> {
+    return Promise.resolve(`data:image/png;base64,${base64Image}`);
+  }
+
+  partialImageIndexToProgress(partialImageIndex: number): number {
+    if (this.partialImages === null || this.partialImages <= 0) {
+      return 0;
+    }
+
+    return Math.min(1, partialImageIndex / this.partialImages);
+  }
+
+  convertAnnotation(annotation: unknown): Annotation | null {
+    if (!isRecord(annotation)) {
+      return null;
+    }
+
+    switch (annotation.type) {
+      case "file_citation":
+        return this.fileCitationToAnnotation(annotation);
+      case "container_file_citation":
+        return this.containerFileCitationToAnnotation(annotation);
+      case "url_citation":
+        return this.urlCitationToAnnotation(annotation);
+      default:
+        return null;
+    }
+  }
+
+  fileCitationToAnnotation(annotation: unknown): Annotation | null {
+    if (!isRecord(annotation)) {
+      return null;
+    }
+
+    const filename = nonEmptyStringValue(annotation.filename);
+    if (!filename) {
+      return null;
+    }
+
+    return {
+      type: "annotation",
+      source: { type: "file", filename, title: filename },
+      index: numberValue(annotation.index),
+    };
+  }
+
+  containerFileCitationToAnnotation(annotation: unknown): Annotation | null {
+    if (!isRecord(annotation)) {
+      return null;
+    }
+
+    const filename = nonEmptyStringValue(annotation.filename);
+    if (!filename) {
+      return null;
+    }
+
+    return {
+      type: "annotation",
+      source: { type: "file", filename, title: filename },
+      index: numberValue(annotation.end_index),
+    };
+  }
+
+  urlCitationToAnnotation(annotation: unknown): Annotation | null {
+    if (!isRecord(annotation)) {
+      return null;
+    }
+
+    const url = nonEmptyStringValue(annotation.url);
+    const title = stringValue(annotation.title);
+    if (!url || title === null) {
+      return null;
+    }
+
+    return {
+      type: "annotation",
+      source: { type: "url", url, title },
+      index: numberValue(annotation.end_index),
+    };
+  }
+}
+
+export interface ConvertedTextContent {
+  type: "output_text";
+  text: string;
+  annotations: Annotation[];
+}
+
+export function convertTextContentPart(
+  part: unknown,
+  converter: ResponseStreamConverter,
+): ConvertedTextContent | null {
+  if (!isRecord(part)) {
+    return null;
+  }
+
+  if (part.type === "refusal") {
+    const text = stringValue(part.refusal);
+    return text === null ? null : { type: "output_text", text, annotations: [] };
+  }
+
+  if (part.type !== "output_text") {
+    return null;
+  }
+
+  const text = stringValue(part.text);
+  if (text === null) {
+    return null;
+  }
+
+  const annotations = Array.isArray(part.annotations)
+    ? part.annotations.flatMap((annotation) => {
+        const converted = converter.convertAnnotation(annotation);
+        return converted ? [converted] : [];
+      })
+    : [];
+
+  return { type: "output_text", text, annotations };
+}
+
+export const defaultResponseStreamConverter = new ResponseStreamConverter();

package/src/agents/context.ts

@@ -0,0 +1,190 @@
+import type { Task, ThreadItem, Workflow, WorkflowSummary } from "../types/core";
+import { ThreadStreamEventSchema, type ThreadStreamEvent } from "../types/server";
+import { streamWidget as streamWidgetEvents, type WidgetRoot } from "../widgets";
+import type { AgentContextOptions, JsonObject } from "./types";
+import {
+  appendWorkflowTask,
+  createWorkflowItem,
+  finishWorkflow,
+  normalizeWorkflowTask,
+  shouldEmitWorkflowAdded,
+  updateWorkflowTaskEvent,
+  workflowAddedEvent,
+} from "./workflows";
+
+class AsyncEventQueue<T> implements AsyncIterable<T> {
+  private readonly values: T[] = [];
+  private readonly waiting: Array<(result: IteratorResult<T>) => void> = [];
+  private closed = false;
+
+  push(value: T): void {
+    if (this.closed) {
+      throw new Error("Cannot stream events after the agent context has completed.");
+    }
+
+    const resolve = this.waiting.shift();
+
+    if (resolve) {
+      resolve({ done: false, value });
+      return;
+    }
+
+    this.values.push(value);
+  }
+
+  close(): void {
+    if (this.closed) {
+      return;
+    }
+
+    this.closed = true;
+
+    for (const resolve of this.waiting.splice(0)) {
+      resolve({ done: true, value: undefined });
+    }
+  }
+
+  async next(): Promise<IteratorResult<T>> {
+    const value = this.values.shift();
+
+    if (value !== undefined) {
+      return { done: false, value };
+    }
+
+    if (this.closed) {
+      return { done: true, value: undefined };
+    }
+
+    return new Promise((resolve) => {
+      this.waiting.push(resolve);
+    });
+  }
+
+  [Symbol.asyncIterator](): AsyncIterator<T> {
+    return {
+      next: () => this.next(),
+      return: async () => {
+        this.close();
+        return { done: true, value: undefined };
+      },
+    };
+  }
+}
+
+export class ClientToolCall {
+  readonly arguments: JsonObject;
+
+  constructor(
+    readonly name: string,
+    args: JsonObject = {},
+  ) {
+    this.arguments = args;
+  }
+}
+
+type WorkflowItem = Extract<ThreadItem, { type: "workflow" }>;
+
+export class AgentContext<TContext> {
+  readonly thread: AgentContextOptions<TContext>["thread"];
+  readonly store: AgentContextOptions<TContext>["store"];
+  readonly context: TContext;
+  readonly previousResponseId: string | null;
+  workflowItem: WorkflowItem | null = null;
+  private readonly now: () => Date | string;
+  private readonly queue = new AsyncEventQueue<ThreadStreamEvent>();
+  private clientToolCall: ClientToolCall | null = null;
+
+  constructor(options: AgentContextOptions<TContext>) {
+    this.thread = options.thread;
+    this.store = options.store;
+    this.context = options.context;
+    this.previousResponseId = options.previousResponseId ?? null;
+    this.now = options.now ?? (() => new Date());
+  }
+
+  stream(event: ThreadStreamEvent): void {
+    this.queue.push(ThreadStreamEventSchema.parse(event));
+  }
+
+  async streamWidget(
+    widget: WidgetRoot | AsyncIterable<WidgetRoot>,
+    copyText?: string | null,
+  ): Promise<void> {
+    for await (const event of streamWidgetEvents(this.thread, widget, {
+      copyText,
+      generateId: (itemType) => this.store.generateItemId(itemType, this.thread, this.context),
+      now: () => this.createdAt(),
+    })) {
+      this.stream(event);
+    }
+  }
+
+  events(): AsyncIterable<ThreadStreamEvent> {
+    return this.queue;
+  }
+
+  closeEvents(): void {
+    this.queue.close();
+  }
+
+  startWorkflow(workflow: Workflow): void {
+    const item = createWorkflowItem(this, workflow);
+    this.workflowItem = item;
+
+    if (shouldEmitWorkflowAdded(item.workflow)) {
+      this.stream(workflowAddedEvent(item));
+    }
+  }
+
+  addWorkflowTask(task: Task): void {
+    const normalizedTask = normalizeWorkflowTask(task);
+
+    if (!this.workflowItem) {
+      this.workflowItem = createWorkflowItem(this, {
+        type: "custom",
+        tasks: [],
+        expanded: false,
+      });
+    }
+
+    const shouldEmitAdded =
+      this.workflowItem.workflow.type !== "reasoning" &&
+      this.workflowItem.workflow.tasks.length === 0;
+    const event = appendWorkflowTask(this.workflowItem, normalizedTask);
+
+    this.stream(shouldEmitAdded ? workflowAddedEvent(this.workflowItem) : event);
+  }
+
+  updateWorkflowTask(task: Task, taskIndex: number): void {
+    if (!this.workflowItem) {
+      throw new Error("Workflow is not set");
+    }
+
+    this.stream(updateWorkflowTaskEvent(this.workflowItem, task, taskIndex));
+  }
+
+  endWorkflow(summary?: WorkflowSummary, expanded = false): void {
+    const event = finishWorkflow(this, summary, expanded);
+
+    if (event) {
+      this.stream(event);
+    }
+  }
+
+  setClientToolCall(toolCall: ClientToolCall): void {
+    if (this.clientToolCall) {
+      throw new Error("Only one client tool call can be set per response.");
+    }
+
+    this.clientToolCall = toolCall;
+  }
+
+  getClientToolCall(): ClientToolCall | null {
+    return this.clientToolCall;
+  }
+
+  createdAt(): string {
+    const value = this.now();
+    return typeof value === "string" ? value : value.toISOString();
+  }
+}