Status: Spec-frozen skeleton. No implementations yet.
The wire format for a portable chat agent widget — backend-agnostic, framework-agnostic. This repo exists so the spec can stabilise before any consumer commits a wire format. Lesson learned the hard way from bug-report-widget: once three apps have shipped a chat surface with their own field names, retroactive standardisation is expensive. So this time we publish the contract first.
The design rationale lives at design-patterns/chat-api-pattern.md. Read that for the why. This repo is the what: a formal OpenAPI spec, typed DTOs, and scaffolded packages waiting for a real consumer to motivate implementation.
A portable, self-injecting chat widget that any web app can drop in:
<script src="/lib/chat-widget.js" defer></script>…and a backend the widget posts to, in your stack of choice:
# Python (Flask)
from chat_widget import create_chat_blueprint
app.register_blueprint(create_chat_blueprint(
agent_loop=your_agent_loop, # callable: (messages, tools) -> turn result
store=your_conversation_store, # optional; stateless if omitted
preflight=your_gate, # optional; auth + rate + budget
))// Node (Express)
import { createChatRouter } from "chat-widget-node";
app.use("/api/chat", createChatRouter({
agentLoop: yourAgentLoop,
store: yourStore, // optional
preflight: yourGate, // optional
}));The agent loop is injected. The package is wire-format plumbing — it never picks the model provider (Anthropic / OpenAI / etc.) or owns the tools. That's the seam.
| Package | Status | Purpose |
|---|---|---|
packages/spec |
✅ Real | OpenAPI 3.1 + TS types + Python types. The contract. |
packages/widget |
🟡 Scaffold | Vanilla JS self-injecting chat panel. Waiting for first consumer. |
packages/backend-python |
🟡 Scaffold | Flask blueprint + Store Protocol + AgentLoop Protocol. |
packages/backend-node |
🟡 Scaffold | Express router + Store interface + AgentLoop interface. |
packages/cli |
🟡 Scaffold | chat CLI for one-shot turns — useful for smoke tests + scripts. |
e2e/ |
🟡 Scaffold | Cross-stack contract suite — same scenarios against both backends. |
Per the chat-api-pattern doc, three existing chat agents:
- pikpak-platform — closest fit (SSE primary, conversations endpoints, in-flight cancellation, hard tool-loop cap). Migrating pikpak first would prove the abstraction.
- leap-timesheet — needs cost guardrails / kill switch / prompt caching to come along as configurable preflight steps; Conversations table needs a
Storeadapter. - katja-schedule — stateless-server case; the package's persistence interface must genuinely be optional. Client sends full trimmed history each turn.
Plus future apps (claude-tmux-dashboard could grow a chat surface for tmux-Claude debugging, for example).
Implementation begins when two of those three commit to consuming the package. Until then, this repo is documentation — the spec, typed, in code form, ready to be reviewed.
One endpoint, content-negotiated:
POST /api/chat
Accept: application/json → buffered TurnResponse
Accept: text/event-stream → SSE stream of typed events
GET /api/chat/conversations (404 if persistence off)
POST /api/chat/conversations (create)
GET /api/chat/conversations/{id}/messages (rehydrate)
GET /api/chat/health (cheap probe)
Messages are Anthropic-shaped: {role, content} where content is either a string or an array of typed blocks (text / image / document). Server owns the tool loop; client renders typed SSE events (text_delta, tool_use, tool_result, done, error).
Full spec: packages/spec/openapi.yaml.
MIT. See LICENSE.