@alien/chat-sdk

A reusable chat SDK for building agentic apps on Next.js. Powers the chat in datastreaming-demos/publisher-demo — drop it into any Next.js project and you get the same streaming UI talking to either the Alien platform agentic flow (alienSDK) or Claude directly (claudeSDK).

npm i @alien/chat-sdk

// app/api/chat/route.ts
import { createChatHandler } from "@alien/chat-sdk/next"
import { createToolRegistry, defineTool } from "@alien/chat-sdk/claude"
import { z } from "zod"

const now = defineTool({
  name: "current_time",
  description: "Server-side UTC time.",
  inputSchema: z.object({ timezone: z.string().optional() }),
  handler: async ({ timezone }) => ({
    now: timezone
      ? new Intl.DateTimeFormat("en-US", { timeZone: timezone, dateStyle: "full", timeStyle: "long" }).format(new Date())
      : new Date().toISOString(),
  }),
})

export const POST = createChatHandler({
  claude: {
    apiKey: process.env.ANTHROPIC_API_KEY!,
    system: "You are a concise research assistant.",
    tools: createToolRegistry({ tools: [now] }),
  },
})
export const runtime = "nodejs"
export const dynamic = "force-dynamic"

// app/page.tsx
"use client"
import { ChatPanel, useChat } from "@alien/chat-sdk/react"
import "@alien/chat-sdk/react/styles.css"

export default function Page() {
  const chat = useChat({ endpoint: "/api/chat", mode: "claude" })
  return <ChatPanel chat={chat} />
}

That's it. Streaming, tool-use loop, mode switching, mobile layout — all in.

What you get

• Three runners, one event protocol. claudeSDK calls Anthropic directly; alienSDK drives the Alien platform's agentic workflow; the OpenRouter runner routes the claude mode through OpenRouter's gateway — one key for every vendor, and non-Anthropic models (GPT, Gemini, Llama, …) through the same protocol. All emit the same normalized ChatEvent stream so the UI doesn't know which is running.
• OpenRouter is a one-line switch. provider: "openrouter" on the handler's claude config routes through the gateway in both ephemeral and durable paths; bare Claude ids are auto-namespaced. See OpenRouter.
• Custom tools via defineTool — Zod schemas, typed handlers, run inside your chat handler with full access to the consumer's app context.
• MCP servers as a first-class hook — declare { name, url, headers }, the runner discovers and dispatches their tools alongside your custom ones.
• Server-only auth. API keys stay on the server. Browser only talks to the consumer's own /api/chat.
• Stateful where it matters. Multi-turn memory via previousResponseId for alienSDK (auto-captured); full conversation history for claudeSDK.
• Persistence-ready. chat.serialize() → JSON-safe ChatSnapshot; parseChatSnapshot(...) rehydrates and finalizes mid-stream tools.
• Smoothing on by default. Word-rate typewriter feel at 25ms ticks, per-instance buckets so concurrent subagent streams stay coherent.
• React 19 + Next.js 14+, mobile-friendly, themable via CSS variables.

Subpath exports

| Subpath | Contents | | ---------------------------------- | ------------------------------------------------------------------------- | | @alien/chat-sdk | Isomorphic re-exports: event + message types, snapshot helpers | | @alien/chat-sdk/events | ChatEvent union, encodeEventFrame, readEventStream, parseEventLine| | @alien/chat-sdk/claude | runClaudeSdk, defineTool, createToolRegistry, MCP server types | | @alien/chat-sdk/alien | runAlienSdk for the Alien platform agentic workflow | | @alien/chat-sdk/openrouter | runOpenRouterSdk, resolveOpenRouterModel, openRouterHeaders | | @alien/chat-sdk/next | createChatHandler — POST handler factory for both modes | | @alien/chat-sdk/react | useChat, useChatTimeline, ChatPanel, Message, Composer | | @alien/chat-sdk/react/styles.css | Default styles. Override via --chat-sdk-* CSS variables |

Topic guides

Each guide is short and focused. Start with Architecture if you're new.

• Architecture — how the pieces fit together
• useChat hook — options, returned API, persistence, smoothing
• Event protocol — ChatEvent reference, wire format, helpers
• Tools — defineTool, tool registry, lifecycle hooks
• MCP servers — attaching servers, name prefixing, dispatch
• Components — ChatPanel props, custom shells, theming
• alienSDK — Alien platform specifics: instances, response ids, cost breakdowns
• OpenRouter — route the claude mode through OpenRouter; multi-vendor, model namespacing, reasoning tradeoff
• Bridge pattern — using onEvent to feed your own observability/analytics

Installation

The package is currently distributed via the internal GitLab package registry or via a built tarball:

# from the GitLab package registry (recommended)
npm i @alien/chat-sdk --registry https://gitlab.com/api/v4/projects/<id>/packages/npm

# from a local tarball (during development)
cd path/to/chat-sdk && npm pack
npm i ./alien-chat-sdk-0.3.0.tgz

Peer deps: react >= 18, react-dom >= 18, next >= 14 (optional). The package brings its own zod, @anthropic-ai/sdk, ai, @ai-sdk/openai, @openrouter/ai-sdk-provider.

Verified

v0.3.0 powers the chat in datastreaming-demos/publisher-demo. End-to-end against the Alien alpha platform: 10 concurrent subagents (3 planners + 6 specialists + 1 critic), 14 tool calls, custom defineTools, MCP server attached, real cost-breakdown events flowing through. See CHANGELOG.md for the full v0.1 → v0.3 history.

v0.6.0's OpenRouter runner is verified live against openrouter.ai across three vendors — anthropic/claude-sonnet-4-6, openai/gpt-4.1, google/gemini-2.5-flash — each streaming text and completing a full tool loop (tool-call → tool-result → final answer), with Claude and Gemini streaming thinking-delta. Reproduce with scripts/smoke-openrouter.mjs.

License

MIT.