create-theokit 1.0.10 → 1.0.12

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-theokit",
-  "version": "1.0.10",
+  "version": "1.0.12",
   "type": "module",
   "description": "Scaffold a new TheoKit project",
   "license": "Apache-2.0",

package/templates/default/CLAUDE.md

@@ -12,6 +12,7 @@ This project includes TheoKit-aware skills that activate automatically when you
 | theokit-agents | `**/*agent*`, `**/*tool*`, `**/*Agent*`, `**/*Tool*` | @Agent, @Tool, @Toolbox decorators, LLM integration |
 | theokit-database | `**/*schema*`, `**/*db*`, `**/drizzle*`, `**/*migration*`, `**/*seed*` | Drizzle ORM, SQLite, schema patterns, migrations |
 | theokit-frontend | `app/**` | File-based routing, layouts, theoFetch, useAgentStream |
+| theokit-ui | `app/**`, `**/*Chat*`, `**/*Sidebar*`, `**/*Theme*` | @theokit/ui components: ChatThread, ChatMessage, CodeBlock, Sidebar, theming |
 | theokit-config | `theo.config*`, `**/*config*` | defineConfig options, plugins, security, storage |
 
 ### Settings

package/templates/default/dot-claude/skills/theokit-agents/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: theokit-agents
-description: TheoKit agent/LLM integration — @Agent, @Tool, @Toolbox decorators, streaming, memory
+description: TheoKit agent/LLM integration — two streaming surfaces (decorator vs manual), @Tool, @Toolbox, memory
 user-invocable: false
 paths:
   - "**/*agent*"
@@ -13,31 +13,51 @@ paths:
 
 # TheoKit Agents & Tools
 
-## @Agent Decorator
+## Two Streaming Surfaces — pick one per endpoint
+
+TheoKit ships two ways to create agent endpoints. Use ONE per endpoint, not both.
+
+| Surface | Server | Events | Client | When to use |
+|---------|--------|--------|--------|-------------|
+| **Manual** (recommended for most apps) | `defineAgentEndpoint({ handler: async function* })` | `AgentEvent` (Message, ToolCall, Result, Error) | `useAgentStream()` / `consumeAgentStream()` | Full control over the LLM loop — you write the generator |
+| **Decorator** (`@theokit/agents`) | `@Agent` class → auto-generated route | `AgentStreamEvent` (TextDelta, ToolCall, Done...) | (same client hooks work) | Declarative — framework manages LLM loop via `@MainLoop` |
+
+### Surface 1: Manual (defineAgentEndpoint)
 
 ```typescript
-import { Agent, MainLoop, Hook, Memory, Budget } from '@theokit/agents'
+// server/routes/agents/assistant.ts
+import { defineAgentEndpoint } from 'theokit/server/define'
+import type { AgentEvent } from 'theokit'
+
+export const POST = defineAgentEndpoint({
+  handler: async function* ({ body }): AsyncGenerator<AgentEvent> {
+    // You control the LLM loop
+    yield { type: 'message', content: 'Thinking...' }
+    const result = await callLLM(body.message)
+    yield { type: 'message', content: result }
+  },
+})
+```
+
+### Surface 2: Decorator (@Agent)
+
+```typescript
+// server/agents/assistant.agent.ts
+import { Agent, MainLoop, Tool, Toolbox } from '@theokit/agents'
 
 @Agent({
-  model: 'openai/gpt-4o-mini',     // Required: LLM model
-  systemPrompt: 'You are a helpful task assistant.',
+  model: 'openai/gpt-4o-mini',
+  systemPrompt: 'You are a helpful assistant.',
 })
-@Memory({ provider: 'built-in', scope: 'per-user' })  // Optional
-@Budget({ maxCostUsd: 1.00, window: 'daily' })         // Optional
 export class AssistantAgent {
   @MainLoop({ strategy: 'react', maxIterations: 5 })
   async run() {
-    // Framework handles the LLM loop
-  }
-
-  @Hook('before:llm-call')
-  async onBeforeLLM(ctx) {
-    // Intercept before each LLM call
+    // Framework handles the LLM loop via @theokit/sdk
   }
 }
 ```
 
-Convention: `AssistantAgent` class name maps to `GET/POST /api/agents/assistant`.
+Convention: `AssistantAgent` → `POST /api/agents/assistant`
 
 ## @Tool Decorator
 
@@ -50,56 +70,63 @@ export class TaskTools {
   @Tool({
     name: 'list_tasks',
     description: 'List all tasks, optionally filtered by status',
-    input: z.object({
-      done: z.boolean().optional(),
-    }),
+    input: z.object({ done: z.boolean().optional() }),
   })
   async listTasks({ done }: { done?: boolean }) {
-    const all = db.select().from(tasks).all()
-    return done !== undefined ? all.filter(t => t.done === done) : all
-  }
-
-  @Tool({
-    name: 'create_task',
-    description: 'Create a new task with a title',
-    input: z.object({
-      title: z.string().min(1),
-    }),
-  })
-  async createTask({ title }: { title: string }) {
-    return db.insert(tasks).values({ title }).returning().get()
+    return db.select().from(tasks).all()
   }
 }
 ```
 
-## Frontend — useAgentStream
+## Client — useAgentStream (React hook)
+
+Works with BOTH surfaces. Transport: `fetch` POST + `ReadableStream` (SSE).
 
 ```typescript
 import { useAgentStream } from 'theokit/client'
 
 function ChatUI() {
-  const { status, events, send } = useAgentStream('/api/agents/assistant')
+  const { status, events, send, reset } = useAgentStream('/api/agents/assistant')
 
   return (
     <div>
-      {events.map(e => <p key={e.id}>{e.content}</p>)}
+      {status === 'streaming' && <p>Thinking...</p>}
+      {events.map(e => (
+        <div key={e.id}>
+          {e.type === 'message' && <p>{e.content}</p>}
+          {e.type === 'tool_call' && <p>Using tool: {e.name}</p>}
+        </div>
+      ))}
       <button onClick={() => send({ message: 'Hello' })}>Send</button>
     </div>
   )
 }
 ```
 
+### Non-React: consumeAgentStream
+
+```typescript
+import { consumeAgentStream } from 'theokit/client'
+
+const stream = consumeAgentStream('/api/agents/assistant', { body: { message: 'Hi' } })
+for await (const event of stream) {
+  console.log(event.type, event.content)
+}
+```
+
 ## Rules
 
 - Tool `name` and `description` are ALWAYS explicit — never inferred from method names (G4)
 - Tool `input` uses Zod schema — same pattern as defineRoute
 - `@UseGuards()` works on agents (shared with HTTP pipeline)
-- `@UseInterceptors()` and `@UseFilters()` on agents are metadata-only (emit warnings, not enforced at runtime)
+- `@UseInterceptors()` and `@UseFilters()` on agents are metadata-only (emit warnings)
 - Agent runtime is `@theokit/sdk` — NEVER call LLM APIs directly via fetch
+- Pick ONE surface per endpoint — don't mix defineAgentEndpoint with @Agent for the same route
 
 ## Anti-patterns
 
-- NEVER call OpenAI/Anthropic/OpenRouter APIs directly — use @Agent + @Tool
+- NEVER call OpenAI/Anthropic/OpenRouter APIs directly — use @Agent or defineAgentEndpoint
 - NEVER reimplement tool calling loop — the SDK handles it
-- NEVER store conversations manually — use @Memory
+- NEVER store conversations manually — use @Memory (decorator) or SDK persistence
 - NEVER infer tool capability from method name — always provide explicit `name` + `description`
+- NEVER mix both surfaces for the same endpoint — pick manual OR decorator

package/templates/default/dot-claude/skills/theokit-frontend/SKILL.md

@@ -43,18 +43,21 @@ import { createAppClient } from 'theokit/client'
 
 const client = createAppClient()
 
-// Proxy pattern — method names match route structure
 const tasks = await client.tasks.GET()
 const task = await client.tasks[':id'].GET({ params: { id: 1 } })
 const created = await client.tasks.POST({ body: { title: 'New' } })
 ```
 
-## Agent Streaming (useAgentStream)
+## Agent Streaming
+
+Three client APIs, all from `theokit/client`:
+
+### useAgentStream (React hook — most common)
 
 ```typescript
 import { useAgentStream } from 'theokit/client'
 
-function ChatComponent() {
+function ChatUI() {
   const { status, events, send, reset } = useAgentStream('/api/agents/assistant')
 
   return (
@@ -66,12 +69,34 @@ function ChatComponent() {
           {event.type === 'tool_call' && <p>Using tool: {event.name}</p>}
         </div>
       ))}
-      <input onSubmit={e => send({ message: e.target.value })} />
+      <button onClick={() => send({ message: 'Hello' })}>Send</button>
     </div>
   )
 }
 ```
 
+### consumeAgentStream (non-React, async iterable)
+
+```typescript
+import { consumeAgentStream } from 'theokit/client'
+
+const stream = consumeAgentStream('/api/agents/assistant', {
+  body: { message: 'Hello' },
+})
+for await (const event of stream) {
+  console.log(event.type, event.content)
+}
+```
+
+### parseSSEChunk (low-level SSE parser)
+
+```typescript
+import { parseSSEChunk } from 'theokit/client'
+
+// Parse a single SSE line into an AgentEvent (or null)
+const event = parseSSEChunk('data: {"type":"message","content":"Hello"}')
+```
+
 ## Path Aliases
 
 ```typescript
@@ -83,7 +108,7 @@ Configured in `tsconfig.json` — works in both server and app code.
 
 ## Anti-patterns
 
-- NEVER use `fetch('/api/...')` directly — use `theoFetch` for type safety
+- NEVER use raw `fetch('/api/...')` — use `theoFetch` for type safety
 - NEVER create pages outside `app/` — they won't be discovered by the router
 - NEVER import server code directly in `app/` — use theoFetch or server actions
 - NEVER use `useEffect` + `fetch` for data loading — use theoFetch or useAgentStream

package/templates/default/dot-claude/skills/theokit-ui/SKILL.md

@@ -0,0 +1,157 @@
+---
+name: theokit-ui
+description: "@theokit/ui component library — chat UI (ChatThread, ChatMessage, ChatComposer, CodeBlock), theming, providers, sidebar"
+user-invocable: false
+paths:
+  - "app/**"
+  - "**/*Chat*"
+  - "**/*chat*"
+  - "**/*Sidebar*"
+  - "**/*sidebar*"
+  - "**/*theme*"
+  - "**/*Theme*"
+---
+
+# @theokit/ui — AI Chat Component Library
+
+`@theokit/ui` is an optional peer dependency. If installed, it provides ready-made components for chat UIs, theming, and layout. **Never build custom equivalents** of components `@theokit/ui` provides.
+
+## Package Identity
+
+The published package is `@theokit/ui` (NOT `@usetheo/ui` — that was the old name).
+
+```bash
+# Install from npm
+npm install @theokit/ui
+
+# Or link from source (development)
+npm link ../theo-ui    # if you have the source repo
+```
+
+## Provider Setup (required before using any component)
+
+```typescript
+// app/layout.tsx
+import '@theokit/ui/styles.css'
+import { TheoUIProvider, ThemeProvider } from '@theokit/ui'
+
+export default function Layout({ children }) {
+  return (
+    <TheoUIProvider>
+      <ThemeProvider>
+        {children}
+      </ThemeProvider>
+    </TheoUIProvider>
+  )
+}
+```
+
+## Chat Components
+
+### Full Chat Page (typical assembly)
+
+```typescript
+import {
+  PageShell,
+  Sidebar,
+  SessionListItem,
+  ChatThread,
+  ChatMessage,
+  ChatMessageContent,
+  ChatComposer,
+} from '@theokit/ui'
+import { useAgentStream } from 'theokit/client'
+
+function ChatPage() {
+  const { status, events, send } = useAgentStream('/api/agents/assistant')
+
+  return (
+    <PageShell sidebar={
+      <Sidebar>
+        {sessions.map(s => (
+          <SessionListItem key={s.id} title={s.title} onClick={() => select(s)} />
+        ))}
+      </Sidebar>
+    }>
+      <ChatThread>
+        {messages.map(m => (
+          <ChatMessage key={m.id} role={m.role}>
+            <ChatMessageContent markdown={m.content} />
+          </ChatMessage>
+        ))}
+      </ChatThread>
+
+      <ChatComposer
+        disabled={status === 'streaming'}
+        onSubmit={text => send({ message: text })}
+      />
+    </PageShell>
+  )
+}
+```
+
+### Individual Components
+
+| Component | Purpose | Key Props |
+|-----------|---------|-----------|
+| `ChatThread` | Scrollable message container | `children` (ChatMessage elements) |
+| `ChatMessage` | Single message bubble | `role: 'user' \| 'assistant'`, `children` |
+| `ChatMessageContent` | Markdown + code rendering | `markdown: string` (handles streaming partial) |
+| `CodeBlock` | Syntax-highlighted code | `code: string`, `language?: string` (uses shiki, lazy-loaded) |
+| `ChatComposer` | Message input + submit | `onSubmit: (text) => void`, `disabled?: boolean` |
+| `PageShell` | App layout with sidebar slot | `sidebar?: ReactNode`, `children` |
+| `Sidebar` | Collapsible side panel | `children` |
+| `SessionListItem` | Session entry in sidebar | `title: string`, `onClick`, `active?: boolean` |
+
+### Other Useful Components
+
+| Component | Purpose |
+|-----------|---------|
+| `Button`, `Input`, `Textarea` | Form primitives (themed) |
+| `ToolCallCard` | Display agent tool invocations |
+| `AgentStream` | Lower-level stream renderer |
+| `ThemeSwitcher` | Light/dark mode toggle |
+| `Avatar` | User/agent avatar |
+| `Alert` | Status messages |
+
+## Peer Dependencies (install only what you use)
+
+**Chat/markdown path** (most apps need these):
+```bash
+npm install mdast-util-from-markdown mdast-util-to-hast mdast-util-gfm \
+  hast-util-to-jsx-runtime hast-util-sanitize hast-util-from-html \
+  micromark-extension-gfm unist-util-visit unist-util-visit-parents shiki
+```
+
+**DO NOT install** unless you use the specific components:
+- `mermaid` — only for diagram rendering components
+- `katex` — only for math/LaTeX rendering
+- `roughjs` / `perfect-freehand` — only for whiteboard/drawing components
+
+## Theming
+
+```typescript
+import { defineTheme, ThemeProvider } from '@theokit/ui'
+
+// Built-in themes
+import { dracula, oneDark, githubDark, anthropicStyle } from '@theokit/ui'
+
+// Custom theme
+const myTheme = defineTheme({
+  name: 'my-theme',
+  colors: { primary: '#3b82f6', background: '#0a0a0a' },
+})
+
+<ThemeProvider theme={myTheme}>
+  {children}
+</ThemeProvider>
+```
+
+## Anti-patterns
+
+- NEVER build a custom chat message component — use `ChatMessage` + `ChatMessageContent`
+- NEVER build a custom markdown renderer — `ChatMessageContent` handles it (including streaming partial fences)
+- NEVER build a custom code highlighter — `CodeBlock` uses shiki (lazy-loaded)
+- NEVER import from `@usetheo/ui` — that's the deprecated package name; use `@theokit/ui`
+- NEVER install ALL peer deps — only install the peers for components you actually use
+- NEVER use components without wrapping in `TheoUIProvider` + `ThemeProvider` first