Add unmanged sample with a minimal backend (#98)

* Move existing starter app to managed-chatkit

* Add chatkit example

* Update CI

* Small fixes

* Remove to_message_content

* Simplify

* Next -> Vite

.github/workflows/ci.yml

@@ -6,9 +6,62 @@ on:
   pull_request:
 
 jobs:
-  build:
-    name: Install, Lint, and Build
+  python:
+    name: Python checks (${{ matrix.project }})
     runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        project:
+          - chatkit/backend
+          - managed-chatkit/backend
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+
+      - name: Install dependencies (${{ matrix.project }})
+        working-directory: ${{ matrix.project }}
+        env:
+          PIP_DISABLE_PIP_VERSION_CHECK: "1"
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install ".[dev]"
+          python -m pip install mypy
+
+      - name: Syntax check (${{ matrix.project }})
+        working-directory: ${{ matrix.project }}
+        run: python -m compileall app
+
+      - name: Ruff lint (${{ matrix.project }})
+        working-directory: ${{ matrix.project }}
+        run: python -m ruff check app
+
+      - name: Ruff format check (${{ matrix.project }})
+        working-directory: ${{ matrix.project }}
+        run: |
+          python -m ruff format --check app || {
+            echo "::error ::Ruff format check failed. Run 'python -m ruff format app' locally to apply formatting.";
+            exit 1;
+          }
+
+      - name: mypy (${{ matrix.project }})
+        working-directory: ${{ matrix.project }}
+        run: python -m mypy app --ignore-missing-imports
+
+  node:
+    name: Node checks (${{ matrix.project }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        project:
+          - managed-chatkit/frontend
+          - chatkit/frontend
 
     steps:
       - name: Checkout repository
@@ -18,14 +71,18 @@ jobs:
         uses: actions/setup-node@v4
         with:
           node-version: 22
+          cache-dependency-path: ${{ matrix.project }}/package-lock.json
           cache: "npm"
 
       - name: Install dependencies
+        working-directory: ${{ matrix.project }}
         run: npm ci
 
       - name: Run ESLint
+        working-directory: ${{ matrix.project }}
         run: npm run lint
 
       - name: Run build
+        working-directory: ${{ matrix.project }}
         run: npm run build
   

README.md

@@ -1,71 +1,8 @@
-# ChatKit Starter Template
+# OpenAI ChatKit Starter Templates
 
-[![MIT License](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
-![NextJS](https://img.shields.io/badge/Built_with-NextJS-blue)
-![OpenAI API](https://img.shields.io/badge/Powered_by-OpenAI_API-orange)
+This repository contains two starter apps as reference implementations of minimal ChatKit integrations.
 
-This repository is the simplest way to bootstrap a [ChatKit](http://openai.github.io/chatkit-js/) application. It ships with a minimal Next.js UI, the ChatKit web component, and a ready-to-use session endpoint so you can experiment with OpenAI-hosted workflows built using [Agent Builder](https://platform.openai.com/agent-builder).
+You can run the following examples:
 
-## What You Get
-
-- Next.js app with `<openai-chatkit>` web component and theming controls
-- API endpoint for creating a session at [`app/api/create-session/route.ts`](app/api/create-session/route.ts)
-- Config file for starter prompts, theme, placeholder text, and greeting message
-
-## Getting Started
-
-### 1. Install dependencies
-
-```bash
-npm install
-```
-
-### 2. Create your environment file
-
-Copy the example file and fill in the required values:
-
-```bash
-cp .env.example .env.local
-```
-
-You can get your workflow id from the [Agent Builder](https://platform.openai.com/agent-builder) interface, after clicking "Publish":
-
-<img src="./public/docs/workflow.jpg" width=500 />
-
-You can get your OpenAI API key from the [OpenAI API Keys](https://platform.openai.com/api-keys) page.
-
-### 3. Configure ChatKit credentials
-
-Update `.env.local` with the variables that match your setup.
-
-- `OPENAI_API_KEY` — This must be an API key created **within the same org & project as your Agent Builder**. If you already have a different `OPENAI_API_KEY` env variable set in your terminal session, that one will take precedence over the key in `.env.local` one (this is how a Next.js app works). So, **please run `unset OPENAI_API_KEY` (`set OPENAI_API_KEY=` for Windows OS) beforehand**.
-- `NEXT_PUBLIC_CHATKIT_WORKFLOW_ID` — This is the ID of the workflow you created in [Agent Builder](https://platform.openai.com/agent-builder), which starts with `wf_...`
-- (optional) `CHATKIT_API_BASE` - This is a customizable base URL for the ChatKit API endpoint
-
-> Note: if your workflow is using a model requiring organization verification, such as GPT-5, make sure you verify your organization first. Visit your [organization settings](https://platform.openai.com/settings/organization/general) and click on "Verify Organization".
-
-### 4. Run the app
-
-```bash
-npm run dev
-```
-
-Visit `http://localhost:3000` and start chatting. Use the prompts on the start screen to verify your workflow connection, then customize the UI or prompt list in [`lib/config.ts`](lib/config.ts) and [`components/ChatKitPanel.tsx`](components/ChatKitPanel.tsx).
-
-### 5. Deploy your app
-
-```bash
-npm run build
-```
-
-Before deploying your app, you need to verify the domain by adding it to the [Domain allowlist](https://platform.openai.com/settings/organization/security/domain-allowlist) on your dashboard.
-
-## Customization Tips
-
-- Adjust starter prompts, greeting text, [chatkit theme](https://chatkit.studio/playground), and placeholder copy in [`lib/config.ts`](lib/config.ts).
-- Update the event handlers inside [`components/.tsx`](components/ChatKitPanel.tsx) to integrate with your product analytics or storage.
-
-## References
-
-- [ChatKit JavaScript Library](http://openai.github.io/chatkit-js/)
-- [Advanced Self-Hosting Examples](https://github.com/openai/openai-chatkit-advanced-samples)
+- [**ChatKit**](chatkit) - example of a self-hosted ChatKit integration.
+- [**Managed ChatKit**](managed-chatkit) – example of a managed ChatKit integration with hosted workflows.

app/App.tsx

@@ -1,34 +0,0 @@
-"use client";
-
-import { useCallback } from "react";
-import { ChatKitPanel, type FactAction } from "@/components/ChatKitPanel";
-import { useColorScheme } from "@/hooks/useColorScheme";
-
-export default function App() {
-  const { scheme, setScheme } = useColorScheme();
-
-  const handleWidgetAction = useCallback(async (action: FactAction) => {
-    if (process.env.NODE_ENV !== "production") {
-      console.info("[ChatKitPanel] widget action", action);
-    }
-  }, []);
-
-  const handleResponseEnd = useCallback(() => {
-    if (process.env.NODE_ENV !== "production") {
-      console.debug("[ChatKitPanel] response end");
-    }
-  }, []);
-
-  return (
-    <main className="flex min-h-screen flex-col items-center justify-end bg-slate-100 dark:bg-slate-950">
-      <div className="mx-auto w-full max-w-5xl">
-        <ChatKitPanel
-          theme={scheme}
-          onWidgetAction={handleWidgetAction}
-          onResponseEnd={handleResponseEnd}
-          onThemeRequest={setScheme}
-        />
-      </div>
-    </main>
-  );
-}

app/api/create-session/route.ts

@@ -1,283 +0,0 @@
-import { WORKFLOW_ID } from "@/lib/config";
-
-export const runtime = "edge";
-
-interface CreateSessionRequestBody {
-  workflow?: { id?: string | null } | null;
-  scope?: { user_id?: string | null } | null;
-  workflowId?: string | null;
-  chatkit_configuration?: {
-    file_upload?: {
-      enabled?: boolean;
-    };
-  };
-}
-
-const DEFAULT_CHATKIT_BASE = "https://api.openai.com";
-const SESSION_COOKIE_NAME = "chatkit_session_id";
-const SESSION_COOKIE_MAX_AGE = 60 * 60 * 24 * 30; // 30 days
-
-export async function POST(request: Request): Promise<Response> {
-  if (request.method !== "POST") {
-    return methodNotAllowedResponse();
-  }
-  let sessionCookie: string | null = null;
-  try {
-    const openaiApiKey = process.env.OPENAI_API_KEY;
-    if (!openaiApiKey) {
-      return new Response(
-        JSON.stringify({
-          error: "Missing OPENAI_API_KEY environment variable",
-        }),
-        {
-          status: 500,
-          headers: { "Content-Type": "application/json" },
-        }
-      );
-    }
-
-    const parsedBody = await safeParseJson<CreateSessionRequestBody>(request);
-    const { userId, sessionCookie: resolvedSessionCookie } =
-      await resolveUserId(request);
-    sessionCookie = resolvedSessionCookie;
-    const resolvedWorkflowId =
-      parsedBody?.workflow?.id ?? parsedBody?.workflowId ?? WORKFLOW_ID;
-
-    if (process.env.NODE_ENV !== "production") {
-      console.info("[create-session] handling request", {
-        resolvedWorkflowId,
-        body: JSON.stringify(parsedBody),
-      });
-    }
-
-    if (!resolvedWorkflowId) {
-      return buildJsonResponse(
-        { error: "Missing workflow id" },
-        400,
-        { "Content-Type": "application/json" },
-        sessionCookie
-      );
-    }
-
-    const apiBase = process.env.CHATKIT_API_BASE ?? DEFAULT_CHATKIT_BASE;
-    const url = `${apiBase}/v1/chatkit/sessions`;
-    const upstreamResponse = await fetch(url, {
-      method: "POST",
-      headers: {
-        "Content-Type": "application/json",
-        Authorization: `Bearer ${openaiApiKey}`,
-        "OpenAI-Beta": "chatkit_beta=v1",
-      },
-      body: JSON.stringify({
-        workflow: { id: resolvedWorkflowId },
-        user: userId,
-        chatkit_configuration: {
-          file_upload: {
-            enabled:
-              parsedBody?.chatkit_configuration?.file_upload?.enabled ?? false,
-          },
-        },
-      }),
-    });
-
-    if (process.env.NODE_ENV !== "production") {
-      console.info("[create-session] upstream response", {
-        status: upstreamResponse.status,
-        statusText: upstreamResponse.statusText,
-      });
-    }
-
-    const upstreamJson = (await upstreamResponse.json().catch(() => ({}))) as
-      | Record<string, unknown>
-      | undefined;
-
-    if (!upstreamResponse.ok) {
-      const upstreamError = extractUpstreamError(upstreamJson);
-      console.error("OpenAI ChatKit session creation failed", {
-        status: upstreamResponse.status,
-        statusText: upstreamResponse.statusText,
-        body: upstreamJson,
-      });
-      return buildJsonResponse(
-        {
-          error:
-            upstreamError ??
-            `Failed to create session: ${upstreamResponse.statusText}`,
-          details: upstreamJson,
-        },
-        upstreamResponse.status,
-        { "Content-Type": "application/json" },
-        sessionCookie
-      );
-    }
-
-    const clientSecret = upstreamJson?.client_secret ?? null;
-    const expiresAfter = upstreamJson?.expires_after ?? null;
-    const responsePayload = {
-      client_secret: clientSecret,
-      expires_after: expiresAfter,
-    };
-
-    return buildJsonResponse(
-      responsePayload,
-      200,
-      { "Content-Type": "application/json" },
-      sessionCookie
-    );
-  } catch (error) {
-    console.error("Create session error", error);
-    return buildJsonResponse(
-      { error: "Unexpected error" },
-      500,
-      { "Content-Type": "application/json" },
-      sessionCookie
-    );
-  }
-}
-
-export async function GET(): Promise<Response> {
-  return methodNotAllowedResponse();
-}
-
-function methodNotAllowedResponse(): Response {
-  return new Response(JSON.stringify({ error: "Method Not Allowed" }), {
-    status: 405,
-    headers: { "Content-Type": "application/json" },
-  });
-}
-
-async function resolveUserId(request: Request): Promise<{
-  userId: string;
-  sessionCookie: string | null;
-}> {
-  const existing = getCookieValue(
-    request.headers.get("cookie"),
-    SESSION_COOKIE_NAME
-  );
-  if (existing) {
-    return { userId: existing, sessionCookie: null };
-  }
-
-  const generated =
-    typeof crypto.randomUUID === "function"
-      ? crypto.randomUUID()
-      : Math.random().toString(36).slice(2);
-
-  return {
-    userId: generated,
-    sessionCookie: serializeSessionCookie(generated),
-  };
-}
-
-function getCookieValue(
-  cookieHeader: string | null,
-  name: string
-): string | null {
-  if (!cookieHeader) {
-    return null;
-  }
-
-  const cookies = cookieHeader.split(";");
-  for (const cookie of cookies) {
-    const [rawName, ...rest] = cookie.split("=");
-    if (!rawName || rest.length === 0) {
-      continue;
-    }
-    if (rawName.trim() === name) {
-      return rest.join("=").trim();
-    }
-  }
-  return null;
-}
-
-function serializeSessionCookie(value: string): string {
-  const attributes = [
-    `${SESSION_COOKIE_NAME}=${encodeURIComponent(value)}`,
-    "Path=/",
-    `Max-Age=${SESSION_COOKIE_MAX_AGE}`,
-    "HttpOnly",
-    "SameSite=Lax",
-  ];
-
-  if (process.env.NODE_ENV === "production") {
-    attributes.push("Secure");
-  }
-  return attributes.join("; ");
-}
-
-function buildJsonResponse(
-  payload: unknown,
-  status: number,
-  headers: Record<string, string>,
-  sessionCookie: string | null
-): Response {
-  const responseHeaders = new Headers(headers);
-
-  if (sessionCookie) {
-    responseHeaders.append("Set-Cookie", sessionCookie);
-  }
-
-  return new Response(JSON.stringify(payload), {
-    status,
-    headers: responseHeaders,
-  });
-}
-
-async function safeParseJson<T>(req: Request): Promise<T | null> {
-  try {
-    const text = await req.text();
-    if (!text) {
-      return null;
-    }
-    return JSON.parse(text) as T;
-  } catch {
-    return null;
-  }
-}
-
-function extractUpstreamError(
-  payload: Record<string, unknown> | undefined
-): string | null {
-  if (!payload) {
-    return null;
-  }
-
-  const error = payload.error;
-  if (typeof error === "string") {
-    return error;
-  }
-
-  if (
-    error &&
-    typeof error === "object" &&
-    "message" in error &&
-    typeof (error as { message?: unknown }).message === "string"
-  ) {
-    return (error as { message: string }).message;
-  }
-
-  const details = payload.details;
-  if (typeof details === "string") {
-    return details;
-  }
-
-  if (details && typeof details === "object" && "error" in details) {
-    const nestedError = (details as { error?: unknown }).error;
-    if (typeof nestedError === "string") {
-      return nestedError;
-    }
-    if (
-      nestedError &&
-      typeof nestedError === "object" &&
-      "message" in nestedError &&
-      typeof (nestedError as { message?: unknown }).message === "string"
-    ) {
-      return (nestedError as { message: string }).message;
-    }
-  }
-
-  if (typeof payload.message === "string") {
-    return payload.message;
-  }
-  return null;
-}

app/layout.tsx

@@ -1,26 +0,0 @@
-import Script from "next/script";
-import type { Metadata } from "next";
-import "./globals.css";
-
-export const metadata: Metadata = {
-  title: "AgentKit demo",
-  description: "Demo of ChatKit with hosted workflow",
-};
-
-export default function RootLayout({
-  children,
-}: Readonly<{
-  children: React.ReactNode;
-}>) {
-  return (
-    <html lang="en">
-      <head>
-        <Script
-          src="https://cdn.platform.openai.com/deployments/chatkit/chatkit.js"
-          strategy="beforeInteractive"
-        />
-      </head>
-      <body className="antialiased">{children}</body>
-    </html>
-  );
-}

app/page.tsx

@@ -1,5 +0,0 @@
-import App from "./App";
-
-export default function Home() {
-  return <App />;
-}

chatkit/.env.example

@@ -0,0 +1,3 @@
+OPENAI_API_KEY=sk-proj-...
+VITE_CHATKIT_API_URL=http://127.0.0.1:8000/chatkit
+VITE_CHATKIT_API_DOMAIN_KEY=domain_pk_local_dev

chatkit/.gitignore

@@ -0,0 +1,3 @@
+node_modules/
+.env*
+!.env.example

chatkit/README.md

@@ -0,0 +1,32 @@
+# ChatKit Starter
+
+Minimal Vite + React UI paired with a FastAPI backend that forwards chat
+requests to OpenAI through the ChatKit server library.
+
+## Quick start
+
+```bash
+npm install
+npm run dev
+```
+
+What happens:
+
+- `npm run dev` starts the FastAPI backend on `127.0.0.1:8000` and the Vite
+  frontend on `127.0.0.1:3000` with a proxy at `/chatkit`.
+
+## Required environment
+
+- `OPENAI_API_KEY` (backend)
+- `VITE_CHATKIT_API_URL` (optional, defaults to `/chatkit`)
+- `VITE_CHATKIT_API_DOMAIN_KEY` (optional, defaults to `domain_pk_localhost_dev`)
+
+Set `OPENAI_API_KEY` in your shell or in `.env.local` at the repo root before
+running the backend. Register a production domain key in the OpenAI dashboard
+and set `VITE_CHATKIT_API_DOMAIN_KEY` when deploying.
+
+## Customize
+
+- Update UI and connection settings in `frontend/src/lib/config.ts`.
+- Adjust layout in `frontend/src/components/ChatKitPanel.tsx`.
+- Swap the in-memory store in `backend/app/server.py` for persistence.

chatkit/backend/.gitignore

@@ -0,0 +1,9 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.venv/
+.env
+.ruff_cache/
+.pytest_cache/
+.coverage/
+*.log

chatkit/backend/app/__init__.py

@@ -0,0 +1 @@
+"""Minimal ChatKit backend package."""

chatkit/backend/app/assistant.py

@@ -0,0 +1,31 @@
+"""Simple streaming assistant wired to ChatKit."""
+
+from __future__ import annotations
+
+from typing import Any, Annotated
+
+from agents import Agent
+from chatkit.agents import AgentContext
+from pydantic import ConfigDict, Field
+from .memory_store import MemoryStore
+
+MODEL = "gpt-4.1-mini"
+
+
+class StarterAgentContext(AgentContext):
+    """Minimal context passed into the ChatKit agent runner."""
+
+    model_config = ConfigDict(arbitrary_types_allowed=True)
+    request_context: dict[str, Any]
+    # The store is excluded so it isn't serialized into prompts.
+    store: Annotated[MemoryStore, Field(exclude=True)]
+
+
+assistant_agent = Agent[StarterAgentContext](
+    model=MODEL,
+    name="Starter Assistant",
+    instructions=(
+        "You are a concise, helpful assistant. "
+        "Keep replies short and focus on directly answering the user's request."
+    ),
+)

chatkit/backend/app/main.py

@@ -0,0 +1,35 @@
+"""FastAPI entrypoint for the ChatKit starter backend."""
+
+from __future__ import annotations
+
+from chatkit.server import StreamingResult
+from fastapi import FastAPI, Request
+from fastapi.middleware.cors import CORSMiddleware
+from fastapi.responses import JSONResponse, Response, StreamingResponse
+
+from .server import StarterChatServer
+
+app = FastAPI(title="ChatKit Starter API")
+
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=["*"],
+    allow_credentials=True,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+chatkit_server = StarterChatServer()
+
+
+@app.post("/chatkit")
+async def chatkit_endpoint(request: Request) -> Response:
+    """Proxy the ChatKit web component payload to the server implementation."""
+    payload = await request.body()
+    result = await chatkit_server.process(payload, {"request": request})
+
+    if isinstance(result, StreamingResult):
+        return StreamingResponse(result, media_type="text/event-stream")
+    if hasattr(result, "json"):
+        return Response(content=result.json, media_type="application/json")
+    return JSONResponse(result)

chatkit/backend/app/memory_store.py

@@ -0,0 +1,196 @@
+"""
+Simple in-memory store compatible with the ChatKit Store interface.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import datetime
+from typing import Any, Dict, List
+
+from chatkit.store import NotFoundError, Store
+from chatkit.types import Attachment, Page, Thread, ThreadItem, ThreadMetadata
+
+
+@dataclass
+class _ThreadState:
+    thread: ThreadMetadata
+    items: List[ThreadItem]
+
+
+class MemoryStore(Store[dict[str, Any]]):
+    """Simple in-memory store compatible with the ChatKit Store interface."""
+
+    def __init__(self) -> None:
+        self._threads: Dict[str, _ThreadState] = {}
+        # Attachments intentionally unsupported; use a real store that enforces auth.
+
+    @staticmethod
+    def _coerce_thread_metadata(thread: ThreadMetadata | Thread) -> ThreadMetadata:
+        """Return thread metadata without any embedded items."""
+        has_items = isinstance(thread, Thread) or "items" in getattr(
+            thread, "model_fields_set", set()
+        )
+        if not has_items:
+            return thread.model_copy(deep=True)
+
+        data = thread.model_dump()
+        data.pop("items", None)
+        return ThreadMetadata(**data).model_copy(deep=True)
+
+    # -- Thread metadata -------------------------------------------------
+    async def load_thread(
+        self, thread_id: str, context: dict[str, Any]
+    ) -> ThreadMetadata:
+        state = self._threads.get(thread_id)
+        if not state:
+            raise NotFoundError(f"Thread {thread_id} not found")
+        return self._coerce_thread_metadata(state.thread)
+
+    async def save_thread(
+        self, thread: ThreadMetadata, context: dict[str, Any]
+    ) -> None:
+        metadata = self._coerce_thread_metadata(thread)
+        state = self._threads.get(thread.id)
+        if state:
+            state.thread = metadata
+        else:
+            self._threads[thread.id] = _ThreadState(
+                thread=metadata,
+                items=[],
+            )
+
+    async def load_threads(
+        self,
+        limit: int,
+        after: str | None,
+        order: str,
+        context: dict[str, Any],
+    ) -> Page[ThreadMetadata]:
+        threads = sorted(
+            (
+                self._coerce_thread_metadata(state.thread)
+                for state in self._threads.values()
+            ),
+            key=lambda t: t.created_at or datetime.min,
+            reverse=(order == "desc"),
+        )
+
+        if after:
+            index_map = {thread.id: idx for idx, thread in enumerate(threads)}
+            start = index_map.get(after, -1) + 1
+        else:
+            start = 0
+
+        slice_threads = threads[start : start + limit + 1]
+        has_more = len(slice_threads) > limit
+        slice_threads = slice_threads[:limit]
+        next_after = slice_threads[-1].id if has_more and slice_threads else None
+        return Page(
+            data=slice_threads,
+            has_more=has_more,
+            after=next_after,
+        )
+
+    async def delete_thread(self, thread_id: str, context: dict[str, Any]) -> None:
+        self._threads.pop(thread_id, None)
+
+    # -- Thread items ----------------------------------------------------
+    def _thread_state(self, thread_id: str) -> _ThreadState:
+        state = self._threads.get(thread_id)
+        if state is None:
+            state = _ThreadState(
+                thread=ThreadMetadata(id=thread_id, created_at=datetime.utcnow()),
+                items=[],
+            )
+            self._threads[thread_id] = state
+        return state
+
+    def _items(self, thread_id: str) -> List[ThreadItem]:
+        state = self._thread_state(thread_id)
+        return state.items
+
+    async def load_thread_items(
+        self,
+        thread_id: str,
+        after: str | None,
+        limit: int,
+        order: str,
+        context: dict[str, Any],
+    ) -> Page[ThreadItem]:
+        items = [item.model_copy(deep=True) for item in self._items(thread_id)]
+        items.sort(
+            key=lambda item: getattr(item, "created_at", datetime.utcnow()),
+            reverse=(order == "desc"),
+        )
+
+        if after:
+            index_map = {item.id: idx for idx, item in enumerate(items)}
+            start = index_map.get(after, -1) + 1
+        else:
+            start = 0
+
+        slice_items = items[start : start + limit + 1]
+        has_more = len(slice_items) > limit
+        slice_items = slice_items[:limit]
+        next_after = slice_items[-1].id if has_more and slice_items else None
+        return Page(data=slice_items, has_more=has_more, after=next_after)
+
+    async def add_thread_item(
+        self, thread_id: str, item: ThreadItem, context: dict[str, Any]
+    ) -> None:
+        self._items(thread_id).append(item.model_copy(deep=True))
+
+    async def save_item(
+        self, thread_id: str, item: ThreadItem, context: dict[str, Any]
+    ) -> None:
+        items = self._items(thread_id)
+        for idx, existing in enumerate(items):
+            if existing.id == item.id:
+                items[idx] = item.model_copy(deep=True)
+                return
+        items.append(item.model_copy(deep=True))
+
+    async def load_item(
+        self, thread_id: str, item_id: str, context: dict[str, Any]
+    ) -> ThreadItem:
+        for item in self._items(thread_id):
+            if item.id == item_id:
+                return item.model_copy(deep=True)
+        raise NotFoundError(f"Item {item_id} not found")
+
+    async def delete_thread_item(
+        self, thread_id: str, item_id: str, context: dict[str, Any]
+    ) -> None:
+        items = self._items(thread_id)
+        self._threads[thread_id].items = [item for item in items if item.id != item_id]
+
+    # -- Files -----------------------------------------------------------
+    # These methods are not currently used but required to be compatible with the Store interface.
+
+    async def save_attachment(
+        self,
+        attachment: Attachment,
+        context: dict[str, Any],
+    ) -> None:
+        raise NotImplementedError(
+            "MemoryStore does not persist attachments. Provide a Store implementation "
+            "that enforces authentication and authorization before enabling uploads."
+        )
+
+    async def load_attachment(
+        self,
+        attachment_id: str,
+        context: dict[str, Any],
+    ) -> Attachment:
+        raise NotImplementedError(
+            "MemoryStore does not load attachments. Provide a Store implementation "
+            "that enforces authentication and authorization before enabling uploads."
+        )
+
+    async def delete_attachment(
+        self, attachment_id: str, context: dict[str, Any]
+    ) -> None:
+        raise NotImplementedError(
+            "MemoryStore does not delete attachments because they are never stored."
+        )

chatkit/backend/app/server.py

@@ -0,0 +1,54 @@
+"""ChatKit server that streams responses from a single assistant."""
+
+from __future__ import annotations
+
+from typing import Any, AsyncIterator
+
+from agents import Runner
+from chatkit.agents import simple_to_agent_input, stream_agent_response
+from chatkit.server import ChatKitServer
+from chatkit.types import ThreadMetadata, ThreadStreamEvent, UserMessageItem
+
+from .assistant import StarterAgentContext, assistant_agent
+from .memory_store import MemoryStore
+
+MAX_RECENT_ITEMS = 30
+
+
+class StarterChatServer(ChatKitServer[dict[str, Any]]):
+    """Server implementation that keeps conversation state in memory."""
+
+    def __init__(self) -> None:
+        self.store: MemoryStore = MemoryStore()
+        super().__init__(self.store)
+
+    async def respond(
+        self,
+        thread: ThreadMetadata,
+        item: UserMessageItem | None,
+        context: dict[str, Any],
+    ) -> AsyncIterator[ThreadStreamEvent]:
+        items_page = await self.store.load_thread_items(
+            thread.id,
+            after=None,
+            limit=MAX_RECENT_ITEMS,
+            order="desc",
+            context=context,
+        )
+        items = list(reversed(items_page.data))
+        agent_input = await simple_to_agent_input(items)
+
+        agent_context = StarterAgentContext(
+            thread=thread,
+            store=self.store,
+            request_context=context,
+        )
+
+        result = Runner.run_streamed(
+            assistant_agent,
+            agent_input,
+            context=agent_context,
+        )
+
+        async for event in stream_agent_response(agent_context, result):
+            yield event

chatkit/backend/pyproject.toml

@@ -0,0 +1,21 @@
+[project]
+name = "chatkit-starter-backend"
+version = "0.1.0"
+description = "Minimal FastAPI backend for the self-hosted ChatKit starter"
+requires-python = ">=3.11"
+dependencies = [
+    "fastapi>=0.114,<0.116",
+    "uvicorn[standard]>=0.36,<0.37",
+    "openai>=1.40",
+    "openai-chatkit>=1.4.0,<2",
+]
+
+[project.optional-dependencies]
+dev = [
+    "ruff>=0.6.4,<0.7",
+]
+
+[build-system]
+requires = ["setuptools>=68.0", "wheel"]
+build-backend = "setuptools.build_meta"
+

chatkit/backend/scripts/run.sh

@@ -0,0 +1,40 @@
+#!/usr/bin/env bash
+
+# Simple helper to start the ChatKit backend (similar to cat-lounge UX).
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PROJECT_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+
+cd "$PROJECT_ROOT"
+
+if [ ! -d ".venv" ]; then
+  echo "Creating virtual env in $PROJECT_ROOT/.venv ..."
+  python -m venv .venv
+fi
+
+source .venv/bin/activate
+
+echo "Installing backend deps (editable) ..."
+pip install -e . >/dev/null
+
+# Load env vars from the repo's .env.local (if present) so OPENAI_API_KEY
+# does not need to be exported manually.
+ENV_FILE="$PROJECT_ROOT/../.env.local"
+if [ -z "${OPENAI_API_KEY:-}" ] && [ -f "$ENV_FILE" ]; then
+  echo "Sourcing OPENAI_API_KEY from $ENV_FILE"
+  # shellcheck disable=SC1090
+  set -a
+  . "$ENV_FILE"
+  set +a
+fi
+
+if [ -z "${OPENAI_API_KEY:-}" ]; then
+  echo "Set OPENAI_API_KEY in your environment or in .env.local before running this script."
+  exit 1
+fi
+
+echo "Starting ChatKit backend on http://127.0.0.1:8000 ..."
+exec uvicorn app.main:app --reload --host 127.0.0.1 --port 8000
+

chatkit/frontend/.gitignore

@@ -0,0 +1,7 @@
+node_modules/
+dist/
+.DS_Store
+.next/
+npm-debug.log*
+*.tsbuildinfo
+next-env.d.ts

chatkit/frontend/eslint.config.mjs

@@ -0,0 +1,37 @@
+import js from "@eslint/js";
+import globals from "globals";
+import reactHooks from "eslint-plugin-react-hooks";
+import reactRefresh from "eslint-plugin-react-refresh";
+import tseslint from "@typescript-eslint/eslint-plugin";
+import tsParser from "@typescript-eslint/parser";
+
+export default [
+  {
+    ignores: ["node_modules/**", "dist/**", ".next/**"],
+  },
+  js.configs.recommended,
+  {
+    files: ["**/*.{ts,tsx}"],
+    languageOptions: {
+      parser: tsParser,
+      parserOptions: {
+        projectService: true,
+        ecmaFeatures: { jsx: true },
+      },
+      globals: { ...globals.browser, ...globals.node },
+    },
+    plugins: {
+      "@typescript-eslint": tseslint,
+      "react-hooks": reactHooks,
+      "react-refresh": reactRefresh,
+    },
+    rules: {
+      ...tseslint.configs["recommended-type-checked"].rules,
+      ...reactHooks.configs.recommended.rules,
+      "react-refresh/only-export-components": [
+        "warn",
+        { allowConstantExport: true },
+      ],
+    },
+  },
+];

chatkit/frontend/index.html

@@ -0,0 +1,15 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>AgentKit demo</title>
+    <link rel="icon" type="image/x-icon" href="/favicon.ico" />
+    <script src="https://cdn.platform.openai.com/deployments/chatkit/chatkit.js"></script>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>
+

chatkit/frontend/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "chatkit-frontend",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "vite build",
+    "preview": "vite preview",
+    "lint": "eslint . --ext ts,tsx --max-warnings=0"
+  },
+  "engines": {
+    "node": ">=18.18",
+    "npm": ">=9"
+  },
+  "dependencies": {
+    "@openai/chatkit-react": ">=1.1.1 <2.0.0",
+    "react": "^19.2.0",
+    "react-dom": "^19.2.0"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.17.0",
+    "@tailwindcss/postcss": "^4",
+    "@types/node": "^22.9.4",
+    "@types/react": "^19.0.8",
+    "@types/react-dom": "^19.0.3",
+    "@typescript-eslint/eslint-plugin": "^8.16.0",
+    "@typescript-eslint/parser": "^8.16.0",
+    "@vitejs/plugin-react-swc": "^3.5.0",
+    "eslint": "^9.17.0",
+    "eslint-plugin-react-hooks": "^5.0.0",
+    "eslint-plugin-react-refresh": "^0.4.16",
+    "globals": "^15.12.0",
+    "postcss": "^8.4.47",
+    "tailwindcss": "^4",
+    "typescript": "^5.6.3",
+    "vite": "^7.1.9"
+  }
+}

postcss.config.mjs → chatkit/frontend/postcss.config.mjs

@@ -1,5 +1,7 @@
 const config = {
-  plugins: ["@tailwindcss/postcss"],
+  plugins: {
+    "@tailwindcss/postcss": {},
+  },
 };
 
 export default config;

chatkit/frontend/src/App.tsx

@@ -0,0 +1,11 @@
+import { ChatKitPanel } from "./components/ChatKitPanel";
+
+export default function App() {
+  return (
+    <main className="flex min-h-screen flex-col items-center justify-end bg-slate-100 dark:bg-slate-950">
+      <div className="mx-auto w-full max-w-5xl">
+        <ChatKitPanel />
+      </div>
+    </main>
+  );
+}

chatkit/frontend/src/components/ChatKitPanel.tsx

@@ -0,0 +1,18 @@
+import { ChatKit, useChatKit } from "@openai/chatkit-react";
+import { CHATKIT_API_DOMAIN_KEY, CHATKIT_API_URL } from "../lib/config";
+
+export function ChatKitPanel() {
+  const chatkit = useChatKit({
+    api: { url: CHATKIT_API_URL, domainKey: CHATKIT_API_DOMAIN_KEY },
+    composer: {
+      // File uploads are disabled for the demo backend.
+      attachments: { enabled: false },
+    },
+  });
+
+  return (
+    <div className="relative pb-8 flex h-[90vh] w-full rounded-2xl flex-col overflow-hidden bg-white shadow-sm transition-colors dark:bg-slate-900">
+      <ChatKit control={chatkit.control} className="block h-full w-full" />
+    </div>
+  );
+}

chatkit/frontend/src/lib/config.ts

@@ -0,0 +1,16 @@
+const readEnvString = (value: unknown): string | undefined =>
+  typeof value === "string" && value.trim().length > 0
+    ? value.trim()
+    : undefined;
+
+export const CHATKIT_API_URL =
+  readEnvString(import.meta.env.VITE_CHATKIT_API_URL) ?? "/chatkit";
+
+/**
+ * ChatKit requires a domain key at runtime. Use the local fallback while
+ * developing, and register a production domain key for deployment:
+ * https://platform.openai.com/settings/organization/security/domain-allowlist
+ */
+export const CHATKIT_API_DOMAIN_KEY =
+  readEnvString(import.meta.env.VITE_CHATKIT_API_DOMAIN_KEY) ??
+  "domain_pk_localhost_dev";

chatkit/frontend/src/main.tsx

@@ -0,0 +1,16 @@
+import { StrictMode } from "react";
+import { createRoot } from "react-dom/client";
+import App from "./App";
+import "./index.css";
+
+const container = document.getElementById("root");
+if (!container) {
+  throw new Error("Root element with id 'root' not found");
+}
+
+createRoot(container).render(
+  <StrictMode>
+    <App />
+  </StrictMode>
+);
+

chatkit/frontend/src/vite-env.d.ts

@@ -0,0 +1,14 @@
+/// <reference types="vite/client" />
+
+declare global {
+  interface ImportMetaEnv {
+    readonly VITE_CHATKIT_API_URL?: string;
+    readonly VITE_CHATKIT_API_DOMAIN_KEY?: string;
+  }
+
+  interface ImportMeta {
+    readonly env: ImportMetaEnv;
+  }
+}
+
+export {};

chatkit/frontend/tsconfig.json

@@ -0,0 +1,17 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "useDefineForClassFields": true,
+    "lib": ["ES2020", "DOM", "DOM.Iterable"],
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "strict": true,
+    "noEmit": true,
+    "esModuleInterop": true,
+    "jsx": "react-jsx"
+  },
+  "include": ["src"],
+  "references": [{ "path": "./tsconfig.node.json" }]
+}

chatkit/frontend/tsconfig.node.json

@@ -0,0 +1,11 @@
+{
+  "compilerOptions": {
+    "composite": true,
+    "module": "ESNext",
+    "moduleResolution": "Node",
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "types": ["node"]
+  },
+  "include": ["vite.config.ts"]
+}

chatkit/frontend/vite.config.ts

@@ -0,0 +1,21 @@
+import * as path from "node:path";
+import { defineConfig } from "vite";
+import react from "@vitejs/plugin-react-swc";
+
+const backendTarget = process.env.CHATKIT_API_BASE ?? "http://127.0.0.1:8000";
+
+export default defineConfig({
+  // Allow env files to live one level above the frontend directory
+  envDir: path.resolve(__dirname, ".."),
+  plugins: [react()],
+  server: {
+    port: 3000,
+    host: "0.0.0.0",
+    proxy: {
+      "/chatkit": {
+        target: backendTarget,
+        changeOrigin: true,
+      },
+    },
+  },
+});

chatkit/package-lock.json

@@ -0,0 +1,327 @@
+{
+  "name": "chatkit",
+  "lockfileVersion": 3,
+  "requires": true,
+  "packages": {
+    "": {
+      "name": "chatkit",
+      "devDependencies": {
+        "concurrently": "^9.1.2"
+      }
+    },
+    "node_modules/ansi-regex": {
+      "version": "5.0.1",
+      "resolved": "https://registry.npmjs.org/ansi-regex/-/ansi-regex-5.0.1.tgz",
+      "integrity": "sha512-quJQXlTSUGL2LH9SUXo8VwsY4soanhgo6LNSm84E1LBcE8s3O0wpdiRzyR9z/ZZJMlMWv37qOOb9pdJlMUEKFQ==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=8"
+      }
+    },
+    "node_modules/ansi-styles": {
+      "version": "4.3.0",
+      "resolved": "https://registry.npmjs.org/ansi-styles/-/ansi-styles-4.3.0.tgz",
+      "integrity": "sha512-zbB9rCJAT1rbjiVDb2hqKFHNYLxgtk8NURxZ3IZwD3F6NtxbXZQCnnSi1Lkx+IDohdPlFp222wVALIheZJQSEg==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "color-convert": "^2.0.1"
+      },
+      "engines": {
+        "node": ">=8"
+      },
+      "funding": {
+        "url": "https://github.com/chalk/ansi-styles?sponsor=1"
+      }
+    },
+    "node_modules/chalk": {
+      "version": "4.1.2",
+      "resolved": "https://registry.npmjs.org/chalk/-/chalk-4.1.2.tgz",
+      "integrity": "sha512-oKnbhFyRIXpUuez8iBMmyEa4nbj4IOQyuhc/wy9kY7/WVPcwIO9VA668Pu8RkO7+0G76SLROeyw9CpQ061i4mA==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "ansi-styles": "^4.1.0",
+        "supports-color": "^7.1.0"
+      },
+      "engines": {
+        "node": ">=10"
+      },
+      "funding": {
+        "url": "https://github.com/chalk/chalk?sponsor=1"
+      }
+    },
+    "node_modules/chalk/node_modules/supports-color": {
+      "version": "7.2.0",
+      "resolved": "https://registry.npmjs.org/supports-color/-/supports-color-7.2.0.tgz",
+      "integrity": "sha512-qpCAvRl9stuOHveKsn7HncJRvv501qIacKzQlO/+Lwxc9+0q2wLyv4Dfvt80/DPn2pqOBsJdDiogXGR9+OvwRw==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "has-flag": "^4.0.0"
+      },
+      "engines": {
+        "node": ">=8"
+      }
+    },
+    "node_modules/cliui": {
+      "version": "8.0.1",
+      "resolved": "https://registry.npmjs.org/cliui/-/cliui-8.0.1.tgz",
+      "integrity": "sha512-BSeNnyus75C4//NQ9gQt1/csTXyo/8Sb+afLAkzAptFuMsod9HFokGNudZpi/oQV73hnVK+sR+5PVRMd+Dr7YQ==",
+      "dev": true,
+      "license": "ISC",
+      "dependencies": {
+        "string-width": "^4.2.0",
+        "strip-ansi": "^6.0.1",
+        "wrap-ansi": "^7.0.0"
+      },
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/color-convert": {
+      "version": "2.0.1",
+      "resolved": "https://registry.npmjs.org/color-convert/-/color-convert-2.0.1.tgz",
+      "integrity": "sha512-RRECPsj7iu/xb5oKYcsFHSppFNnsj/52OVTRKb4zP5onXwVF3zVmmToNcOfGC+CRDpfK/U584fMg38ZHCaElKQ==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "color-name": "~1.1.4"
+      },
+      "engines": {
+        "node": ">=7.0.0"
+      }
+    },
+    "node_modules/color-name": {
+      "version": "1.1.4",
+      "resolved": "https://registry.npmjs.org/color-name/-/color-name-1.1.4.tgz",
+      "integrity": "sha512-dOy+3AuW3a2wNbZHIuMZpTcgjGuLU/uBL/ubcZF9OXbDo8ff4O8yVp5Bf0efS8uEoYo5q4Fx7dY9OgQGXgAsQA==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/concurrently": {
+      "version": "9.2.1",
+      "resolved": "https://registry.npmjs.org/concurrently/-/concurrently-9.2.1.tgz",
+      "integrity": "sha512-fsfrO0MxV64Znoy8/l1vVIjjHa29SZyyqPgQBwhiDcaW8wJc2W3XWVOGx4M3oJBnv/zdUZIIp1gDeS98GzP8Ng==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "chalk": "4.1.2",
+        "rxjs": "7.8.2",
+        "shell-quote": "1.8.3",
+        "supports-color": "8.1.1",
+        "tree-kill": "1.2.2",
+        "yargs": "17.7.2"
+      },
+      "bin": {
+        "conc": "dist/bin/concurrently.js",
+        "concurrently": "dist/bin/concurrently.js"
+      },
+      "engines": {
+        "node": ">=18"
+      },
+      "funding": {
+        "url": "https://github.com/open-cli-tools/concurrently?sponsor=1"
+      }
+    },
+    "node_modules/emoji-regex": {
+      "version": "8.0.0",
+      "resolved": "https://registry.npmjs.org/emoji-regex/-/emoji-regex-8.0.0.tgz",
+      "integrity": "sha512-MSjYzcWNOA0ewAHpz0MxpYFvwg6yjy1NG3xteoqz644VCo/RPgnr1/GGt+ic3iJTzQ8Eu3TdM14SawnVUmGE6A==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/escalade": {
+      "version": "3.2.0",
+      "resolved": "https://registry.npmjs.org/escalade/-/escalade-3.2.0.tgz",
+      "integrity": "sha512-WUj2qlxaQtO4g6Pq5c29GTcWGDyd8itL8zTlipgECz3JesAiiOKotd8JU6otB3PACgG6xkJUyVhboMS+bje/jA==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=6"
+      }
+    },
+    "node_modules/get-caller-file": {
+      "version": "2.0.5",
+      "resolved": "https://registry.npmjs.org/get-caller-file/-/get-caller-file-2.0.5.tgz",
+      "integrity": "sha512-DyFP3BM/3YHTQOCUL/w0OZHR0lpKeGrxotcHWcqNEdnltqFwXVfhEBQ94eIo34AfQpo0rGki4cyIiftY06h2Fg==",
+      "dev": true,
+      "license": "ISC",
+      "engines": {
+        "node": "6.* || 8.* || >= 10.*"
+      }
+    },
+    "node_modules/has-flag": {
+      "version": "4.0.0",
+      "resolved": "https://registry.npmjs.org/has-flag/-/has-flag-4.0.0.tgz",
+      "integrity": "sha512-EykJT/Q1KjTWctppgIAgfSO0tKVuZUjhgMr17kqTumMl6Afv3EISleU7qZUzoXDFTAHTDC4NOoG/ZxU3EvlMPQ==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=8"
+      }
+    },
+    "node_modules/is-fullwidth-code-point": {
+      "version": "3.0.0",
+      "resolved": "https://registry.npmjs.org/is-fullwidth-code-point/-/is-fullwidth-code-point-3.0.0.tgz",
+      "integrity": "sha512-zymm5+u+sCsSWyD9qNaejV3DFvhCKclKdizYaJUuHA83RLjb7nSuGnddCHGv0hk+KY7BMAlsWeK4Ueg6EV6XQg==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=8"
+      }
+    },
+    "node_modules/require-directory": {
+      "version": "2.1.1",
+      "resolved": "https://registry.npmjs.org/require-directory/-/require-directory-2.1.1.tgz",
+      "integrity": "sha512-fGxEI7+wsG9xrvdjsrlmL22OMTTiHRwAMroiEeMgq8gzoLC/PQr7RsRDSTLUg/bZAZtF+TVIkHc6/4RIKrui+Q==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=0.10.0"
+      }
+    },
+    "node_modules/rxjs": {
+      "version": "7.8.2",
+      "resolved": "https://registry.npmjs.org/rxjs/-/rxjs-7.8.2.tgz",
+      "integrity": "sha512-dhKf903U/PQZY6boNNtAGdWbG85WAbjT/1xYoZIC7FAY0yWapOBQVsVrDl58W86//e1VpMNBtRV4MaXfdMySFA==",
+      "dev": true,
+      "license": "Apache-2.0",
+      "dependencies": {
+        "tslib": "^2.1.0"
+      }
+    },
+    "node_modules/shell-quote": {
+      "version": "1.8.3",
+      "resolved": "https://registry.npmjs.org/shell-quote/-/shell-quote-1.8.3.tgz",
+      "integrity": "sha512-ObmnIF4hXNg1BqhnHmgbDETF8dLPCggZWBjkQfhZpbszZnYur5DUljTcCHii5LC3J5E0yeO/1LIMyH+UvHQgyw==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">= 0.4"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/ljharb"
+      }
+    },
+    "node_modules/string-width": {
+      "version": "4.2.3",
+      "resolved": "https://registry.npmjs.org/string-width/-/string-width-4.2.3.tgz",
+      "integrity": "sha512-wKyQRQpjJ0sIp62ErSZdGsjMJWsap5oRNihHhu6G7JVO/9jIB6UyevL+tXuOqrng8j/cxKTWyWUwvSTriiZz/g==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "emoji-regex": "^8.0.0",
+        "is-fullwidth-code-point": "^3.0.0",
+        "strip-ansi": "^6.0.1"
+      },
+      "engines": {
+        "node": ">=8"
+      }
+    },
+    "node_modules/strip-ansi": {
+      "version": "6.0.1",
+      "resolved": "https://registry.npmjs.org/strip-ansi/-/strip-ansi-6.0.1.tgz",
+      "integrity": "sha512-Y38VPSHcqkFrCpFnQ9vuSXmquuv5oXOKpGeT6aGrr3o3Gc9AlVa6JBfUSOCnbxGGZF+/0ooI7KrPuUSztUdU5A==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "ansi-regex": "^5.0.1"
+      },
+      "engines": {
+        "node": ">=8"
+      }
+    },
+    "node_modules/supports-color": {
+      "version": "8.1.1",
+      "resolved": "https://registry.npmjs.org/supports-color/-/supports-color-8.1.1.tgz",
+      "integrity": "sha512-MpUEN2OodtUzxvKQl72cUF7RQ5EiHsGvSsVG0ia9c5RbWGL2CI4C7EpPS8UTBIplnlzZiNuV56w+FuNxy3ty2Q==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "has-flag": "^4.0.0"
+      },
+      "engines": {
+        "node": ">=10"
+      },
+      "funding": {
+        "url": "https://github.com/chalk/supports-color?sponsor=1"
+      }
+    },
+    "node_modules/tree-kill": {
+      "version": "1.2.2",
+      "resolved": "https://registry.npmjs.org/tree-kill/-/tree-kill-1.2.2.tgz",
+      "integrity": "sha512-L0Orpi8qGpRG//Nd+H90vFB+3iHnue1zSSGmNOOCh1GLJ7rUKVwV2HvijphGQS2UmhUZewS9VgvxYIdgr+fG1A==",
+      "dev": true,
+      "license": "MIT",
+      "bin": {
+        "tree-kill": "cli.js"
+      }
+    },
+    "node_modules/tslib": {
+      "version": "2.8.1",
+      "resolved": "https://registry.npmjs.org/tslib/-/tslib-2.8.1.tgz",
+      "integrity": "sha512-oJFu94HQb+KVduSUQL7wnpmqnfmLsOA/nAh6b6EH0wCEoK0/mPeXU6c3wKDV83MkOuHPRHtSXKKU99IBazS/2w==",
+      "dev": true,
+      "license": "0BSD"
+    },
+    "node_modules/wrap-ansi": {
+      "version": "7.0.0",
+      "resolved": "https://registry.npmjs.org/wrap-ansi/-/wrap-ansi-7.0.0.tgz",
+      "integrity": "sha512-YVGIj2kamLSTxw6NsZjoBxfSwsn0ycdesmc4p+Q21c5zPuZ1pl+NfxVdxPtdHvmNVOQ6XSYG4AUtyt/Fi7D16Q==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "ansi-styles": "^4.0.0",
+        "string-width": "^4.1.0",
+        "strip-ansi": "^6.0.0"
+      },
+      "engines": {
+        "node": ">=10"
+      },
+      "funding": {
+        "url": "https://github.com/chalk/wrap-ansi?sponsor=1"
+      }
+    },
+    "node_modules/y18n": {
+      "version": "5.0.8",
+      "resolved": "https://registry.npmjs.org/y18n/-/y18n-5.0.8.tgz",
+      "integrity": "sha512-0pfFzegeDWJHJIAmTLRP2DwHjdF5s7jo9tuztdQxAhINCdvS+3nGINqPd00AphqJR/0LhANUS6/+7SCb98YOfA==",
+      "dev": true,
+      "license": "ISC",
+      "engines": {
+        "node": ">=10"
+      }
+    },
+    "node_modules/yargs": {
+      "version": "17.7.2",
+      "resolved": "https://registry.npmjs.org/yargs/-/yargs-17.7.2.tgz",
+      "integrity": "sha512-7dSzzRQ++CKnNI/krKnYRV7JKKPUXMEh61soaHKg9mrWEhzFWhFnxPxGl+69cD1Ou63C13NUPCnmIcrvqCuM6w==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "cliui": "^8.0.1",
+        "escalade": "^3.1.1",
+        "get-caller-file": "^2.0.5",
+        "require-directory": "^2.1.1",
+        "string-width": "^4.2.3",
+        "y18n": "^5.0.5",
+        "yargs-parser": "^21.1.1"
+      },
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/yargs-parser": {
+      "version": "21.1.1",
+      "resolved": "https://registry.npmjs.org/yargs-parser/-/yargs-parser-21.1.1.tgz",
+      "integrity": "sha512-tVpsJW7DdjecAiFpbIB1e3qxIQsE6NoPc5/eTdrbbIC4h0LVsWhnoa3g+m2HclBIujHzsxZ4VJVA+GUuc2/LBw==",
+      "dev": true,
+      "license": "ISC",
+      "engines": {
+        "node": ">=12"
+      }
+    }
+  }
+}

chatkit/package.json

@@ -0,0 +1,12 @@
+{
+  "name": "chatkit",
+  "private": true,
+  "scripts": {
+    "dev": "concurrently --kill-others-on-fail --names backend,frontend \"npm run backend\" \"npm run frontend\"",
+    "frontend": "npm --prefix frontend install && npm --prefix frontend run dev",
+    "backend": "./backend/scripts/run.sh"
+  },
+  "devDependencies": {
+    "concurrently": "^9.1.2"
+  }
+}

components/ChatKitPanel.tsx

@@ -1,418 +0,0 @@
-"use client";
-
-import { useCallback, useEffect, useRef, useState } from "react";
-import { ChatKit, useChatKit } from "@openai/chatkit-react";
-import {
-  STARTER_PROMPTS,
-  PLACEHOLDER_INPUT,
-  GREETING,
-  CREATE_SESSION_ENDPOINT,
-  WORKFLOW_ID,
-  getThemeConfig,
-} from "@/lib/config";
-import { ErrorOverlay } from "./ErrorOverlay";
-import type { ColorScheme } from "@/hooks/useColorScheme";
-
-export type FactAction = {
-  type: "save";
-  factId: string;
-  factText: string;
-};
-
-type ChatKitPanelProps = {
-  theme: ColorScheme;
-  onWidgetAction: (action: FactAction) => Promise<void>;
-  onResponseEnd: () => void;
-  onThemeRequest: (scheme: ColorScheme) => void;
-};
-
-type ErrorState = {
-  script: string | null;
-  session: string | null;
-  integration: string | null;
-  retryable: boolean;
-};
-
-const isBrowser = typeof window !== "undefined";
-const isDev = process.env.NODE_ENV !== "production";
-
-const createInitialErrors = (): ErrorState => ({
-  script: null,
-  session: null,
-  integration: null,
-  retryable: false,
-});
-
-export function ChatKitPanel({
-  theme,
-  onWidgetAction,
-  onResponseEnd,
-  onThemeRequest,
-}: ChatKitPanelProps) {
-  const processedFacts = useRef(new Set<string>());
-  const [errors, setErrors] = useState<ErrorState>(() => createInitialErrors());
-  const [isInitializingSession, setIsInitializingSession] = useState(true);
-  const isMountedRef = useRef(true);
-  const [scriptStatus, setScriptStatus] = useState<
-    "pending" | "ready" | "error"
-  >(() =>
-    isBrowser && window.customElements?.get("openai-chatkit")
-      ? "ready"
-      : "pending"
-  );
-  const [widgetInstanceKey, setWidgetInstanceKey] = useState(0);
-
-  const setErrorState = useCallback((updates: Partial<ErrorState>) => {
-    setErrors((current) => ({ ...current, ...updates }));
-  }, []);
-
-  useEffect(() => {
-    return () => {
-      isMountedRef.current = false;
-    };
-  }, []);
-
-  useEffect(() => {
-    if (!isBrowser) {
-      return;
-    }
-
-    let timeoutId: number | undefined;
-
-    const handleLoaded = () => {
-      if (!isMountedRef.current) {
-        return;
-      }
-      setScriptStatus("ready");
-      setErrorState({ script: null });
-    };
-
-    const handleError = (event: Event) => {
-      console.error("Failed to load chatkit.js for some reason", event);
-      if (!isMountedRef.current) {
-        return;
-      }
-      setScriptStatus("error");
-      const detail = (event as CustomEvent<unknown>)?.detail ?? "unknown error";
-      setErrorState({ script: `Error: ${detail}`, retryable: false });
-      setIsInitializingSession(false);
-    };
-
-    window.addEventListener("chatkit-script-loaded", handleLoaded);
-    window.addEventListener(
-      "chatkit-script-error",
-      handleError as EventListener
-    );
-
-    if (window.customElements?.get("openai-chatkit")) {
-      handleLoaded();
-    } else if (scriptStatus === "pending") {
-      timeoutId = window.setTimeout(() => {
-        if (!window.customElements?.get("openai-chatkit")) {
-          handleError(
-            new CustomEvent("chatkit-script-error", {
-              detail:
-                "ChatKit web component is unavailable. Verify that the script URL is reachable.",
-            })
-          );
-        }
-      }, 5000);
-    }
-
-    return () => {
-      window.removeEventListener("chatkit-script-loaded", handleLoaded);
-      window.removeEventListener(
-        "chatkit-script-error",
-        handleError as EventListener
-      );
-      if (timeoutId) {
-        window.clearTimeout(timeoutId);
-      }
-    };
-  }, [scriptStatus, setErrorState]);
-
-  const isWorkflowConfigured = Boolean(
-    WORKFLOW_ID && !WORKFLOW_ID.startsWith("wf_replace")
-  );
-
-  useEffect(() => {
-    if (!isWorkflowConfigured && isMountedRef.current) {
-      setErrorState({
-        session: "Set NEXT_PUBLIC_CHATKIT_WORKFLOW_ID in your .env.local file.",
-        retryable: false,
-      });
-      setIsInitializingSession(false);
-    }
-  }, [isWorkflowConfigured, setErrorState]);
-
-  const handleResetChat = useCallback(() => {
-    processedFacts.current.clear();
-    if (isBrowser) {
-      setScriptStatus(
-        window.customElements?.get("openai-chatkit") ? "ready" : "pending"
-      );
-    }
-    setIsInitializingSession(true);
-    setErrors(createInitialErrors());
-    setWidgetInstanceKey((prev) => prev + 1);
-  }, []);
-
-  const getClientSecret = useCallback(
-    async (currentSecret: string | null) => {
-      if (isDev) {
-        console.info("[ChatKitPanel] getClientSecret invoked", {
-          currentSecretPresent: Boolean(currentSecret),
-          workflowId: WORKFLOW_ID,
-          endpoint: CREATE_SESSION_ENDPOINT,
-        });
-      }
-
-      if (!isWorkflowConfigured) {
-        const detail =
-          "Set NEXT_PUBLIC_CHATKIT_WORKFLOW_ID in your .env.local file.";
-        if (isMountedRef.current) {
-          setErrorState({ session: detail, retryable: false });
-          setIsInitializingSession(false);
-        }
-        throw new Error(detail);
-      }
-
-      if (isMountedRef.current) {
-        if (!currentSecret) {
-          setIsInitializingSession(true);
-        }
-        setErrorState({ session: null, integration: null, retryable: false });
-      }
-
-      try {
-        const response = await fetch(CREATE_SESSION_ENDPOINT, {
-          method: "POST",
-          headers: {
-            "Content-Type": "application/json",
-          },
-          body: JSON.stringify({
-            workflow: { id: WORKFLOW_ID },
-            chatkit_configuration: {
-              // enable attachments
-              file_upload: {
-                enabled: true,
-              },
-            },
-          }),
-        });
-
-        const raw = await response.text();
-
-        if (isDev) {
-          console.info("[ChatKitPanel] createSession response", {
-            status: response.status,
-            ok: response.ok,
-            bodyPreview: raw.slice(0, 1600),
-          });
-        }
-
-        let data: Record<string, unknown> = {};
-        if (raw) {
-          try {
-            data = JSON.parse(raw) as Record<string, unknown>;
-          } catch (parseError) {
-            console.error(
-              "Failed to parse create-session response",
-              parseError
-            );
-          }
-        }
-
-        if (!response.ok) {
-          const detail = extractErrorDetail(data, response.statusText);
-          console.error("Create session request failed", {
-            status: response.status,
-            body: data,
-          });
-          throw new Error(detail);
-        }
-
-        const clientSecret = data?.client_secret as string | undefined;
-        if (!clientSecret) {
-          throw new Error("Missing client secret in response");
-        }
-
-        if (isMountedRef.current) {
-          setErrorState({ session: null, integration: null });
-        }
-
-        return clientSecret;
-      } catch (error) {
-        console.error("Failed to create ChatKit session", error);
-        const detail =
-          error instanceof Error
-            ? error.message
-            : "Unable to start ChatKit session.";
-        if (isMountedRef.current) {
-          setErrorState({ session: detail, retryable: false });
-        }
-        throw error instanceof Error ? error : new Error(detail);
-      } finally {
-        if (isMountedRef.current && !currentSecret) {
-          setIsInitializingSession(false);
-        }
-      }
-    },
-    [isWorkflowConfigured, setErrorState]
-  );
-
-  const chatkit = useChatKit({
-    api: { getClientSecret },
-    theme: {
-      colorScheme: theme,
-      ...getThemeConfig(theme),
-    },
-    startScreen: {
-      greeting: GREETING,
-      prompts: STARTER_PROMPTS,
-    },
-    composer: {
-      placeholder: PLACEHOLDER_INPUT,
-      attachments: {
-        // Enable attachments
-        enabled: true,
-      },
-    },
-    threadItemActions: {
-      feedback: false,
-    },
-    onClientTool: async (invocation: {
-      name: string;
-      params: Record<string, unknown>;
-    }) => {
-      if (invocation.name === "switch_theme") {
-        const requested = invocation.params.theme;
-        if (requested === "light" || requested === "dark") {
-          if (isDev) {
-            console.debug("[ChatKitPanel] switch_theme", requested);
-          }
-          onThemeRequest(requested);
-          return { success: true };
-        }
-        return { success: false };
-      }
-
-      if (invocation.name === "record_fact") {
-        const id = String(invocation.params.fact_id ?? "");
-        const text = String(invocation.params.fact_text ?? "");
-        if (!id || processedFacts.current.has(id)) {
-          return { success: true };
-        }
-        processedFacts.current.add(id);
-        void onWidgetAction({
-          type: "save",
-          factId: id,
-          factText: text.replace(/\s+/g, " ").trim(),
-        });
-        return { success: true };
-      }
-
-      return { success: false };
-    },
-    onResponseEnd: () => {
-      onResponseEnd();
-    },
-    onResponseStart: () => {
-      setErrorState({ integration: null, retryable: false });
-    },
-    onThreadChange: () => {
-      processedFacts.current.clear();
-    },
-    onError: ({ error }: { error: unknown }) => {
-      // Note that Chatkit UI handles errors for your users.
-      // Thus, your app code doesn't need to display errors on UI.
-      console.error("ChatKit error", error);
-    },
-  });
-
-  const activeError = errors.session ?? errors.integration;
-  const blockingError = errors.script ?? activeError;
-
-  if (isDev) {
-    console.debug("[ChatKitPanel] render state", {
-      isInitializingSession,
-      hasControl: Boolean(chatkit.control),
-      scriptStatus,
-      hasError: Boolean(blockingError),
-      workflowId: WORKFLOW_ID,
-    });
-  }
-
-  return (
-    <div className="relative pb-8 flex h-[90vh] w-full rounded-2xl flex-col overflow-hidden bg-white shadow-sm transition-colors dark:bg-slate-900">
-      <ChatKit
-        key={widgetInstanceKey}
-        control={chatkit.control}
-        className={
-          blockingError || isInitializingSession
-            ? "pointer-events-none opacity-0"
-            : "block h-full w-full"
-        }
-      />
-      <ErrorOverlay
-        error={blockingError}
-        fallbackMessage={
-          blockingError || !isInitializingSession
-            ? null
-            : "Loading assistant session..."
-        }
-        onRetry={blockingError && errors.retryable ? handleResetChat : null}
-        retryLabel="Restart chat"
-      />
-    </div>
-  );
-}
-
-function extractErrorDetail(
-  payload: Record<string, unknown> | undefined,
-  fallback: string
-): string {
-  if (!payload) {
-    return fallback;
-  }
-
-  const error = payload.error;
-  if (typeof error === "string") {
-    return error;
-  }
-
-  if (
-    error &&
-    typeof error === "object" &&
-    "message" in error &&
-    typeof (error as { message?: unknown }).message === "string"
-  ) {
-    return (error as { message: string }).message;
-  }
-
-  const details = payload.details;
-  if (typeof details === "string") {
-    return details;
-  }
-
-  if (details && typeof details === "object" && "error" in details) {
-    const nestedError = (details as { error?: unknown }).error;
-    if (typeof nestedError === "string") {
-      return nestedError;
-    }
-    if (
-      nestedError &&
-      typeof nestedError === "object" &&
-      "message" in nestedError &&
-      typeof (nestedError as { message?: unknown }).message === "string"
-    ) {
-      return (nestedError as { message: string }).message;
-    }
-  }
-
-  if (typeof payload.message === "string") {
-    return payload.message;
-  }
-
-  return fallback;
-}

components/ErrorOverlay.tsx

@@ -1,44 +0,0 @@
-"use client";
-
-import type { ReactNode } from "react";
-
-type ErrorOverlayProps = {
-  error: string | null;
-  fallbackMessage?: ReactNode;
-  onRetry?: (() => void) | null;
-  retryLabel?: string;
-};
-
-export function ErrorOverlay({
-  error,
-  fallbackMessage,
-  onRetry,
-  retryLabel,
-}: ErrorOverlayProps) {
-  if (!error && !fallbackMessage) {
-    return null;
-  }
-
-  const content = error ?? fallbackMessage;
-
-  if (!content) {
-    return null;
-  }
-
-  return (
-    <div className="pointer-events-none absolute inset-0 z-10 flex h-full w-full flex-col justify-center rounded-[inherit] bg-white/85 p-6 text-center backdrop-blur dark:bg-slate-900/90">
-      <div className="pointer-events-auto mx-auto w-full max-w-md rounded-xl bg-white px-6 py-4 text-lg font-medium text-slate-700 dark:bg-transparent dark:text-slate-100">
-        <div>{content}</div>
-        {error && onRetry ? (
-          <button
-            type="button"
-            className="mt-4 inline-flex items-center justify-center rounded-lg bg-slate-900 px-4 py-2 text-sm font-semibold text-white shadow-none transition hover:bg-slate-800 focus:outline-none focus-visible:ring-2 focus-visible:ring-slate-500 focus-visible:ring-offset-2 dark:bg-slate-100 dark:text-slate-900 dark:hover:bg-slate-200"
-            onClick={onRetry}
-          >
-            {retryLabel ?? "Restart chat"}
-          </button>
-        ) : null}
-      </div>
-    </div>
-  );
-}

eslint.config.mjs

@@ -1,25 +0,0 @@
-import { dirname } from "path";
-import { fileURLToPath } from "url";
-import { FlatCompat } from "@eslint/eslintrc";
-
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = dirname(__filename);
-
-const compat = new FlatCompat({
-  baseDirectory: __dirname,
-});
-
-const eslintConfig = [
-  ...compat.extends("next/core-web-vitals", "next/typescript"),
-  {
-    ignores: [
-      "node_modules/**",
-      ".next/**",
-      "out/**",
-      "build/**",
-      "next-env.d.ts",
-    ],
-  },
-];
-
-export default eslintConfig;

hooks/useColorScheme.ts

@@ -1,178 +0,0 @@
-"use client";
-
-import { useCallback, useEffect, useMemo, useState, useSyncExternalStore } from "react";
-
-export type ColorScheme = "light" | "dark";
-export type ColorSchemePreference = ColorScheme | "system";
-
-const STORAGE_KEY = "chatkit-color-scheme";
-const PREFERS_DARK_QUERY = "(prefers-color-scheme: dark)";
-
-type MediaQueryCallback = (event: MediaQueryListEvent) => void;
-
-function getMediaQuery(): MediaQueryList | null {
-  if (typeof window === "undefined" || typeof window.matchMedia !== "function") {
-    return null;
-  }
-  try {
-    return window.matchMedia(PREFERS_DARK_QUERY);
-  } catch (error) {
-    if (process.env.NODE_ENV !== "production") {
-      console.warn("[useColorScheme] matchMedia failed", error);
-    }
-    return null;
-  }
-}
-
-function getSystemSnapshot(): ColorScheme {
-  const media = getMediaQuery();
-  return media?.matches ? "dark" : "light";
-}
-
-function getServerSnapshot(): ColorScheme {
-  return "light";
-}
-
-function subscribeSystem(listener: () => void): () => void {
-  const media = getMediaQuery();
-  if (!media) {
-    return () => { };
-  }
-
-  const handler: MediaQueryCallback = () => listener();
-
-  if (typeof media.addEventListener === "function") {
-    media.addEventListener("change", handler);
-    return () => media.removeEventListener("change", handler);
-  }
-
-  // Fallback for older browsers or environments.
-  if (typeof media.addListener === "function") {
-    media.addListener(handler);
-    return () => media.removeListener(handler);
-  }
-
-  return () => { };
-}
-
-function readStoredPreference(): ColorSchemePreference | null {
-  if (typeof window === "undefined") {
-    return null;
-  }
-  try {
-    const raw = window.localStorage.getItem(STORAGE_KEY);
-    if (raw === "light" || raw === "dark") {
-      return raw;
-    }
-    return raw === "system" ? "system" : null;
-  } catch (error) {
-    if (process.env.NODE_ENV !== "production") {
-      console.warn("[useColorScheme] Failed to read preference", error);
-    }
-    return null;
-  }
-}
-
-function persistPreference(preference: ColorSchemePreference): void {
-  if (typeof window === "undefined") {
-    return;
-  }
-  try {
-    if (preference === "system") {
-      window.localStorage.removeItem(STORAGE_KEY);
-    } else {
-      window.localStorage.setItem(STORAGE_KEY, preference);
-    }
-  } catch (error) {
-    if (process.env.NODE_ENV !== "production") {
-      console.warn("[useColorScheme] Failed to persist preference", error);
-    }
-  }
-}
-
-function applyDocumentScheme(scheme: ColorScheme): void {
-  if (typeof document === "undefined") {
-    return;
-  }
-  const root = document.documentElement;
-  root.dataset.colorScheme = scheme;
-  root.classList.toggle("dark", scheme === "dark");
-  root.style.colorScheme = scheme;
-}
-
-type UseColorSchemeResult = {
-  scheme: ColorScheme;
-  preference: ColorSchemePreference;
-  setScheme: (scheme: ColorScheme) => void;
-  setPreference: (preference: ColorSchemePreference) => void;
-  resetPreference: () => void;
-};
-
-function useSystemColorScheme(): ColorScheme {
-  return useSyncExternalStore(subscribeSystem, getSystemSnapshot, getServerSnapshot);
-}
-
-export function useColorScheme(
-  initialPreference: ColorSchemePreference = "system"
-): UseColorSchemeResult {
-  const systemScheme = useSystemColorScheme();
-
-  const [preference, setPreferenceState] = useState<ColorSchemePreference>(() => {
-    if (typeof window === "undefined") {
-      return initialPreference;
-    }
-    return readStoredPreference() ?? initialPreference;
-  });
-
-  const scheme = useMemo<ColorScheme>(
-    () => (preference === "system" ? systemScheme : preference),
-    [preference, systemScheme]
-  );
-
-  useEffect(() => {
-    persistPreference(preference);
-  }, [preference]);
-
-  useEffect(() => {
-    applyDocumentScheme(scheme);
-  }, [scheme]);
-
-  useEffect(() => {
-    if (typeof window === "undefined") {
-      return;
-    }
-
-    const handleStorage = (event: StorageEvent) => {
-      if (event.key !== STORAGE_KEY) {
-        return;
-      }
-      setPreferenceState((current) => {
-        const stored = readStoredPreference();
-        return stored ?? current;
-      });
-    };
-
-    window.addEventListener("storage", handleStorage);
-    return () => window.removeEventListener("storage", handleStorage);
-  }, []);
-
-  const setPreference = useCallback((next: ColorSchemePreference) => {
-    setPreferenceState(next);
-  }, []);
-
-  const setScheme = useCallback((next: ColorScheme) => {
-    setPreferenceState(next);
-  }, []);
-
-  const resetPreference = useCallback(() => {
-    setPreferenceState("system");
-  }, []);
-
-  return {
-    scheme,
-    preference,
-    setScheme,
-    setPreference,
-    resetPreference,
-  };
-}

lib/config.ts

@@ -1,35 +0,0 @@
-import { ColorScheme, StartScreenPrompt, ThemeOption } from "@openai/chatkit";
-
-export const WORKFLOW_ID =
-  process.env.NEXT_PUBLIC_CHATKIT_WORKFLOW_ID?.trim() ?? "";
-
-export const CREATE_SESSION_ENDPOINT = "/api/create-session";
-
-export const STARTER_PROMPTS: StartScreenPrompt[] = [
-  {
-    label: "What can you do?",
-    prompt: "What can you do?",
-    icon: "circle-question",
-  },
-];
-
-export const PLACEHOLDER_INPUT = "Ask anything...";
-
-export const GREETING = "How can I help you today?";
-
-export const getThemeConfig = (theme: ColorScheme): ThemeOption => ({
-  color: {
-    grayscale: {
-      hue: 220,
-      tint: 6,
-      shade: theme === "dark" ? -1 : -4,
-    },
-    accent: {
-      primary: theme === "dark" ? "#f1f5f9" : "#0f172a",
-      level: 1,
-    },
-  },
-  radius: "round",
-  // Add other theme options here
-  // chatkit.studio/playground to explore config options
-});

.gitignore → managed-chatkit/.gitignore

@@ -2,6 +2,7 @@
 
 # dependencies
 /node_modules
+/frontend/node_modules
 /.pnp
 .pnp.*
 .yarn/*
@@ -13,12 +14,11 @@
 # testing
 /coverage
 
-# next.js
-/.next/
-/out/
-
 # production
-/build
+build/
+dist/
+/frontend/dist/
+/frontend/.vite
 
 # misc
 .DS_Store
@@ -27,16 +27,15 @@
 # debug
 npm-debug.log*
 yarn-debug.log*
-yarn-error.log*
+yarn-error.log*g
 .pnpm-debug.log*
 
-# env files (can opt-in for committing if needed)
+# env files
 .env*
 !.env.example
-
-# vercel
-.vercel
+/backend/.env*
+/backend/.venv
 
 # typescript
-*.tsbuildinfo
-next-env.d.ts
+*.tsbuildinfog
+/backend/.ruff_cache

managed-chatkit/README.md

@@ -0,0 +1,35 @@
+# Managed ChatKit starter
+
+Vite + React UI that talks to a FastAPI session backend for creating ChatKit
+workflow sessions.
+
+## Quick start
+
+```bash
+npm install           # installs root deps (concurrently)
+npm run dev           # runs FastAPI on :8000 and Vite on :3000
+```
+
+What happens:
+
+- `npm run dev` runs the backend via `backend/scripts/run.sh` (FastAPI +
+  uvicorn) and the frontend via `npm --prefix frontend run dev`.
+- The backend exposes `/api/create-session`, exchanging your workflow id and
+  `OPENAI_API_KEY` for a ChatKit client secret. The Vite dev server proxies
+  `/api/*` to `127.0.0.1:8000`.
+
+## Required environment
+
+- `OPENAI_API_KEY`
+- `VITE_CHATKIT_WORKFLOW_ID`
+- (optional) `CHATKIT_API_BASE` or `VITE_CHATKIT_API_BASE` (defaults to `https://api.openai.com`)
+- (optional) `VITE_API_URL` (override the dev proxy target for `/api`)
+
+Set the env vars in your shell (or process manager) before running. Use a
+workflow id from Agent Builder (starts with `wf_...`) and an API key from the
+same project and organization.
+
+## Customize
+
+- UI: `frontend/src/components/ChatKitPanel.tsx`
+- Session logic: `backend/app/main.py`

managed-chatkit/backend/.gitignore

@@ -0,0 +1,9 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.venv/
+.env
+.ruff_cache/
+.pytest_cache/
+.coverage/
+*.log

managed-chatkit/backend/app/__init__.py

@@ -0,0 +1 @@
+"""Managed ChatKit backend package."""

managed-chatkit/backend/app/main.py

@@ -0,0 +1,166 @@
+"""FastAPI entrypoint for exchanging workflow ids for ChatKit client secrets."""
+
+from __future__ import annotations
+
+import json
+import os
+import uuid
+from typing import Any, Mapping
+
+import httpx
+from fastapi import FastAPI, Request
+from fastapi.middleware.cors import CORSMiddleware
+from fastapi.responses import JSONResponse
+
+DEFAULT_CHATKIT_BASE = "https://api.openai.com"
+SESSION_COOKIE_NAME = "chatkit_session_id"
+SESSION_COOKIE_MAX_AGE_SECONDS = 60 * 60 * 24 * 30  # 30 days
+
+app = FastAPI(title="Managed ChatKit Session API")
+
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=["*"],
+    allow_credentials=True,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+
+@app.get("/health")
+async def health() -> Mapping[str, str]:
+    return {"status": "ok"}
+
+
+@app.post("/api/create-session")
+async def create_session(request: Request) -> JSONResponse:
+    """Exchange a workflow id for a ChatKit client secret."""
+    api_key = os.getenv("OPENAI_API_KEY")
+    if not api_key:
+        return respond({"error": "Missing OPENAI_API_KEY environment variable"}, 500)
+
+    body = await read_json_body(request)
+    workflow_id = resolve_workflow_id(body)
+    if not workflow_id:
+        return respond({"error": "Missing workflow id"}, 400)
+
+    user_id, cookie_value = resolve_user(request.cookies)
+    api_base = chatkit_api_base()
+
+    try:
+        async with httpx.AsyncClient(base_url=api_base, timeout=10.0) as client:
+            upstream = await client.post(
+                "/v1/chatkit/sessions",
+                headers={
+                    "Authorization": f"Bearer {api_key}",
+                    "OpenAI-Beta": "chatkit_beta=v1",
+                    "Content-Type": "application/json",
+                },
+                json={"workflow": {"id": workflow_id}, "user": user_id},
+            )
+    except httpx.RequestError as error:
+        return respond(
+            {"error": f"Failed to reach ChatKit API: {error}"},
+            502,
+            cookie_value,
+        )
+
+    payload = parse_json(upstream)
+    if not upstream.is_success:
+        message = None
+        if isinstance(payload, Mapping):
+            message = payload.get("error")
+        message = message or upstream.reason_phrase or "Failed to create session"
+        return respond({"error": message}, upstream.status_code, cookie_value)
+
+    client_secret = None
+    expires_after = None
+    if isinstance(payload, Mapping):
+        client_secret = payload.get("client_secret")
+        expires_after = payload.get("expires_after")
+
+    if not client_secret:
+        return respond(
+            {"error": "Missing client secret in response"},
+            502,
+            cookie_value,
+        )
+
+    return respond(
+        {"client_secret": client_secret, "expires_after": expires_after},
+        200,
+        cookie_value,
+    )
+
+
+def respond(
+    payload: Mapping[str, Any], status_code: int, cookie_value: str | None = None
+) -> JSONResponse:
+    response = JSONResponse(payload, status_code=status_code)
+    if cookie_value:
+        response.set_cookie(
+            key=SESSION_COOKIE_NAME,
+            value=cookie_value,
+            max_age=SESSION_COOKIE_MAX_AGE_SECONDS,
+            httponly=True,
+            samesite="lax",
+            secure=is_prod(),
+            path="/",
+        )
+    return response
+
+
+def is_prod() -> bool:
+    env = (os.getenv("ENVIRONMENT") or os.getenv("NODE_ENV") or "").lower()
+    return env == "production"
+
+
+async def read_json_body(request: Request) -> Mapping[str, Any]:
+    raw = await request.body()
+    if not raw:
+        return {}
+    try:
+        parsed = json.loads(raw)
+    except json.JSONDecodeError:
+        return {}
+    return parsed if isinstance(parsed, Mapping) else {}
+
+
+def resolve_workflow_id(body: Mapping[str, Any]) -> str | None:
+    workflow = body.get("workflow", {})
+    workflow_id = None
+    if isinstance(workflow, Mapping):
+        workflow_id = workflow.get("id")
+    workflow_id = workflow_id or body.get("workflowId")
+    env_workflow = os.getenv("CHATKIT_WORKFLOW_ID") or os.getenv(
+        "VITE_CHATKIT_WORKFLOW_ID"
+    )
+    if not workflow_id and env_workflow:
+        workflow_id = env_workflow
+    if workflow_id and isinstance(workflow_id, str) and workflow_id.strip():
+        return workflow_id.strip()
+    return None
+
+
+def resolve_user(cookies: Mapping[str, str]) -> tuple[str, str | None]:
+    existing = cookies.get(SESSION_COOKIE_NAME)
+    if existing:
+        return existing, None
+    user_id = str(uuid.uuid4())
+    return user_id, user_id
+
+
+def chatkit_api_base() -> str:
+    return (
+        os.getenv("CHATKIT_API_BASE")
+        or os.getenv("VITE_CHATKIT_API_BASE")
+        or DEFAULT_CHATKIT_BASE
+    )
+
+
+def parse_json(response: httpx.Response) -> Mapping[str, Any]:
+    try:
+        parsed = response.json()
+        return parsed if isinstance(parsed, Mapping) else {}
+    except (json.JSONDecodeError, httpx.DecodingError):
+        return {}

managed-chatkit/backend/pyproject.toml

@@ -0,0 +1,20 @@
+[project]
+name = "managed-chatkit-backend"
+version = "0.1.0"
+description = "FastAPI backend for creating ChatKit workflow sessions"
+requires-python = ">=3.11"
+dependencies = [
+    "fastapi>=0.114,<0.116",
+    "httpx>=0.27,<0.28",
+    "uvicorn[standard]>=0.36,<0.37",
+]
+
+[project.optional-dependencies]
+dev = [
+    "ruff>=0.6.4,<0.7",
+]
+
+[build-system]
+requires = ["setuptools>=68.0", "wheel"]
+build-backend = "setuptools.build_meta"
+

managed-chatkit/backend/scripts/run.sh

@@ -0,0 +1,42 @@
+#!/usr/bin/env bash
+
+# Start the Managed ChatKit FastAPI backend.
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PROJECT_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+
+cd "$PROJECT_ROOT"
+
+if [ ! -d ".venv" ]; then
+  echo "Creating virtual env in $PROJECT_ROOT/.venv ..."
+  python -m venv .venv
+fi
+
+source .venv/bin/activate
+
+echo "Installing backend deps (editable) ..."
+pip install -e . >/dev/null
+
+# Load env vars from the repo's .env.local (if present) so OPENAI_API_KEY
+# does not need to be exported manually.
+ENV_FILE="$PROJECT_ROOT/../.env.local"
+if [ -z "${OPENAI_API_KEY:-}" ] && [ -f "$ENV_FILE" ]; then
+  echo "Sourcing OPENAI_API_KEY from $ENV_FILE"
+  # shellcheck disable=SC1090
+  set -a
+  . "$ENV_FILE"
+  set +a
+fi
+
+if [ -z "${OPENAI_API_KEY:-}" ]; then
+  echo "Set OPENAI_API_KEY in your environment or in .env.local before running this script."
+  exit 1
+fi
+
+export PYTHONPATH="$PROJECT_ROOT${PYTHONPATH:+:$PYTHONPATH}"
+
+echo "Starting Managed ChatKit backend on http://127.0.0.1:8000 ..."
+exec uvicorn app.main:app --reload --host 127.0.0.1 --port 8000
+

managed-chatkit/frontend/eslint.config.mjs

@@ -0,0 +1,56 @@
+import js from "@eslint/js";
+import globals from "globals";
+import reactHooks from "eslint-plugin-react-hooks";
+import reactRefresh from "eslint-plugin-react-refresh";
+import tseslint from "@typescript-eslint/eslint-plugin";
+import tsParser from "@typescript-eslint/parser";
+import { URL } from "node:url";
+
+export default [
+  {
+    ignores: ["node_modules/**", "dist/**", ".next/**"],
+  },
+  js.configs.recommended,
+  {
+    files: ["src/**/*.{ts,tsx}"],
+    languageOptions: {
+      parser: tsParser,
+      parserOptions: {
+        project: ["./tsconfig.json"],
+        tsconfigRootDir: new URL(".", import.meta.url).pathname,
+        ecmaFeatures: { jsx: true },
+      },
+      globals: { ...globals.browser, ...globals.node },
+    },
+    plugins: {
+      "@typescript-eslint": tseslint,
+      "react-hooks": reactHooks,
+      "react-refresh": reactRefresh,
+    },
+    rules: {
+      ...tseslint.configs["recommended-type-checked"].rules,
+      ...reactHooks.configs.recommended.rules,
+      "react-refresh/only-export-components": [
+        "warn",
+        { allowConstantExport: true },
+      ],
+    },
+  },
+  {
+    files: ["vite.config.ts"],
+    languageOptions: {
+      parser: tsParser,
+      parserOptions: {
+        project: ["./tsconfig.node.json"],
+        tsconfigRootDir: new URL(".", import.meta.url).pathname,
+      },
+      globals: { ...globals.node },
+    },
+    plugins: {
+      "@typescript-eslint": tseslint,
+    },
+    rules: {
+      ...tseslint.configs.recommended.rules,
+    },
+  },
+];

managed-chatkit/frontend/index.html

@@ -0,0 +1,15 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>AgentKit demo</title>
+    <link rel="icon" type="image/x-icon" href="/favicon.ico" />
+    <script src="https://cdn.platform.openai.com/deployments/chatkit/chatkit.js"></script>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>
+