create-theokit 1.0.15 → 1.0.17

package/templates/default/app/page.test.tsx

@@ -0,0 +1,36 @@
+// @vitest-environment jsdom
+import { render, screen } from '@testing-library/react'
+import { describe, it, expect } from 'vitest'
+import { ChatThread, ChatMessage, type UIMessage } from '@theokit/ui'
+import Page from './page'
+
+/**
+ * Guards the chat page against `@theokit/ui` API drift (issue #80): a fresh scaffold
+ * must both type-check AND render. Renders the real React tree in jsdom.
+ */
+describe('default chat page', () => {
+  it('renders the empty state + quick actions + composer on first load', () => {
+    render(<Page />)
+    expect(screen.getByText('What should we build today?')).toBeDefined()
+    expect(screen.getByText('Summarize this page')).toBeDefined()
+    expect(screen.getByText('Show available tools')).toBeDefined()
+    expect(screen.getByText('Start a new conversation')).toBeDefined()
+    expect(screen.getByPlaceholderText('Ask the agent…')).toBeDefined()
+    expect(screen.getByLabelText('Open command palette')).toBeDefined()
+  })
+
+  it('ChatMessage accepts a UIMessage and renders its message container (auto-dispatch)', () => {
+    const assistant: UIMessage = {
+      id: 'a-0',
+      role: 'assistant',
+      parts: [{ type: 'text', text: 'Reading src/index.ts', state: 'done' }],
+    }
+    const { container } = render(
+      <ChatThread>
+        <ChatMessage message={assistant} />
+      </ChatThread>,
+    )
+    expect(container.querySelector('[data-slot="chat-message"]')).not.toBeNull()
+    expect(container.querySelector('[data-theo-chat-message="assistant"]')).not.toBeNull()
+  })
+})

package/templates/default/app/page.tsx

@@ -5,57 +5,45 @@ import {
   ChatThread,
   ChatMessage,
   ChatComposer,
-  ToolCallCard,
   AgentStreaming,
   AgentErrorCard,
-  EmptyState,
   QuickActionChips,
   ContextWindowBar,
+  type UIMessage,
+  type QuickAction,
+} from '@theokit/ui'
+import {
+  EmptyState,
   CommandPalette,
   Avatar,
   Tooltip,
   Button,
   ScrollArea,
-  type Message,
-  type QuickAction,
   type CommandItem,
-  type ToolCallStatus,
-} from '@theokit/ui'
+} from '@usetheo/ui'
 import { Sparkles, Wrench, RotateCcw, Command } from 'lucide-react'
-import { useAgentStream } from 'theokit/client'
+import { useAgent } from 'theokit/client'
 
 /**
  * Default scaffold — an Agent Surface, composed entirely from TheoUI.
  *
- *   ChatThread / ChatMessage  → conversation
- *   ToolCallCard              → expandable tool invocations
+ *   ChatThread / ChatMessage  → conversation (ChatMessage auto-dispatches text,
+ *                               tool-call, and reasoning parts of each UIMessage)
  *   AgentStreaming            → streaming indicator
  *   AgentErrorCard            → error display
  *   ChatComposer              → bottom input bar
  *   EmptyState                → first-load screen
  *   ContextWindowBar          → context usage at top
  *   CommandPalette            → ⌘K quick actions
- *   Avatar                    → assistant face in messages
+ *   Avatar                    → assistant/user face in messages
  *   Tooltip                   → hints on icons
  *
- * `useAgentStream` handles SSE consumption, AbortController cleanup, and
- * StrictMode safety. Replace the mock at server/routes/chat.ts with your
- * real LLM provider (OpenAI / Anthropic / local).
+ * `useAgent` binds to the `agents/chat.ts` endpoint, consumes the ai-sdk
+ * `UIMessageStream`, and handles AbortController cleanup + StrictMode safety.
+ * `messages` are the reconstructed ASSISTANT `UIMessage[]`; user turns are tracked
+ * locally and interleaved. Edit `agents/chat.ts` to pick your model / add tools.
  */
 
-type ConversationItem =
-  | { kind: 'message'; id: string; role: 'user' | 'assistant'; content: string; timestamp: string }
-  | {
-      kind: 'tool'
-      id: string
-      tool: string
-      target?: string
-      status: ToolCallStatus
-      output?: string
-      timestamp: string
-    }
-  | { kind: 'error'; id: string; message: string; timestamp: string }
-
 const QUICK_ACTIONS: QuickAction[] = [
   { id: 'summarize', label: 'Summarize this page', icon: Sparkles },
   { id: 'tools', label: 'Show available tools', icon: Wrench },
@@ -69,10 +57,11 @@ const COMMAND_ITEMS: CommandItem[] = QUICK_ACTIONS.map((a) => ({
   group: 'Quick actions',
 }))
 
-// Mock context-window usage — replace with real model state.
+// Display-only context-window hint. The agent's real model lives in `agents/chat.ts`
+// (`model: 'openai/gpt-4o-mini'`); wire real token counts from the stream when you need them.
 const CONTEXT_USED = 4_200
 const CONTEXT_TOTAL = 200_000
-const MODEL_NAME = 'mock-llm'
+const MODEL_NAME = 'gpt-4o-mini'
 
 const ASSISTANT_AVATAR = (
   <Avatar size="sm" tone="primary">
@@ -87,9 +76,9 @@ const USER_AVATAR = (
 
 export default function Page() {
   const [composerValue, setComposerValue] = useState('')
-  const [userMessages, setUserMessages] = useState<ConversationItem[]>([])
+  const [userMessages, setUserMessages] = useState<UIMessage[]>([])
   const [paletteOpen, setPaletteOpen] = useState(false)
-  const { events, send, status, reset } = useAgentStream<{ message: string }>('/api/chat')
+  const { messages, send, status, reset } = useAgent<{ message: string }>('/api/agents/chat')
 
   // ⌘K / Ctrl+K opens the CommandPalette.
   useEffect(() => {
@@ -103,52 +92,29 @@ export default function Page() {
     return () => window.removeEventListener('keydown', onKey)
   }, [])
 
-  const items = useMemo<ConversationItem[]>(() => {
-    const ts = new Date().toISOString()
-    const agentItems: ConversationItem[] = events.map((event, i) => {
-      const id = `e-${i}`
-      switch (event.type) {
-        case 'message':
-          return { kind: 'message', id, role: 'assistant', content: event.content, timestamp: ts }
-        case 'tool_call':
-          return {
-            kind: 'tool',
-            id,
-            tool: event.name,
-            target:
-              typeof event.args === 'object' && event.args !== null
-                ? Object.entries(event.args as Record<string, unknown>)
-                    .map(([k, v]) => `${k}=${JSON.stringify(v)}`)
-                    .join(' ')
-                : undefined,
-            status: 'running',
-            timestamp: ts,
-          }
-        case 'tool_result':
-          return {
-            kind: 'tool',
-            id,
-            tool: event.name,
-            status: 'success',
-            output:
-              typeof event.data === 'string' ? event.data : JSON.stringify(event.data, null, 2),
-            timestamp: ts,
-          }
-        case 'error':
-          return { kind: 'error', id, message: event.message, timestamp: ts }
-      }
-    })
-    return [...userMessages, ...agentItems]
-  }, [userMessages, events])
+  // Interleave local user turns with the reconstructed assistant UIMessages,
+  // turn by turn. `ChatMessage` renders each message's parts (text/tool/reasoning).
+  const thread = useMemo<UIMessage[]>(() => {
+    const out: UIMessage[] = []
+    const turns = Math.max(userMessages.length, messages.length)
+    for (let i = 0; i < turns; i++) {
+      const user = userMessages[i]
+      const assistant = messages[i]
+      if (user) out.push(user)
+      if (assistant) out.push(assistant)
+    }
+    return out
+  }, [userMessages, messages])
 
   function handleSubmit(value: string) {
     const trimmed = value.trim()
     if (!trimmed) return
-    const id = `u-${userMessages.length}`
-    setUserMessages((prev) => [
-      ...prev,
-      { kind: 'message', id, role: 'user', content: trimmed, timestamp: new Date().toISOString() },
-    ])
+    const userMessage: UIMessage = {
+      id: `u-${String(userMessages.length)}`,
+      role: 'user',
+      parts: [{ type: 'text', text: trimmed }],
+    }
+    setUserMessages((prev) => [...prev, userMessage])
     send({ message: trimmed })
     setComposerValue('')
   }
@@ -161,11 +127,12 @@ export default function Page() {
       return
     }
     const action = QUICK_ACTIONS.find((a) => a.id === id)
-    if (action) handleSubmit(action.label)
+    // Quick-action labels are strings; only a string can be sent as a prompt.
+    if (action && typeof action.label === 'string') handleSubmit(action.label)
   }
 
   const isStreaming = status === 'streaming'
-  const isEmpty = items.length === 0 && !isStreaming
+  const isEmpty = thread.length === 0 && !isStreaming
   const hasError = status === 'error'
 
   return (
@@ -186,50 +153,18 @@ export default function Page() {
               eyebrow="Theo Agent"
               icon={Sparkles}
               title="What should we build today?"
-              description="Ask anything. This scaffold ships with a mock LLM at server/routes/chat.ts so you can see the wiring before plugging in a real model."
+              description="Ask anything. This scaffold ships an agent at agents/chat.ts — edit it to pick your model or add tools."
               action={<QuickActionChips actions={QUICK_ACTIONS} onSelect={handleQuickAction} />}
             />
           ) : (
             <ChatThread>
-              {items.map((item) => {
-                if (item.kind === 'message') {
-                  const message: Message = {
-                    id: item.id,
-                    role: item.role,
-                    content: item.content,
-                    timestamp: item.timestamp,
-                    model: item.role === 'assistant' ? MODEL_NAME : undefined,
-                  }
-                  return (
-                    <ChatMessage
-                      key={item.id}
-                      message={message}
-                      avatar={item.role === 'assistant' ? ASSISTANT_AVATAR : USER_AVATAR}
-                    />
-                  )
-                }
-                if (item.kind === 'tool') {
-                  return (
-                    <ToolCallCard
-                      key={item.id}
-                      tool={item.tool}
-                      icon={Wrench}
-                      target={item.target}
-                      status={item.status}
-                      output={item.output}
-                      timestamp={item.timestamp}
-                    />
-                  )
-                }
-                return (
-                  <AgentErrorCard
-                    key={item.id}
-                    kind="model"
-                    title="Agent error"
-                    description={item.message}
-                  />
-                )
-              })}
+              {thread.map((message) => (
+                <ChatMessage
+                  key={message.id}
+                  message={message}
+                  avatar={message.role === 'assistant' ? ASSISTANT_AVATAR : USER_AVATAR}
+                />
+              ))}
               {isStreaming && <AgentStreaming model={MODEL_NAME} />}
             </ChatThread>
           )}
@@ -243,8 +178,8 @@ export default function Page() {
               <AgentErrorCard
                 kind="network"
                 title="Stream ended with an error"
-                description="The connection to the agent endpoint was interrupted. Reset to try again."
-                action={
+                detail="The connection to the agent endpoint was interrupted. Reset to try again."
+                actions={
                   <Button variant="ghost" size="sm" onClick={() => reset()}>
                     Reset
                   </Button>

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

@@ -1,6 +1,6 @@
 ---
 name: theokit-agents
-description: TheoKit agent/LLM integration — two streaming surfaces (decorator vs manual), @Tool, @Toolbox, memory
+description: TheoKit agent/LLM integration — agents/*.ts convention (defineAgent), @Agent decorator (advanced/DI), defineAgentTool, useAgent client hook
 user-invocable: false
 paths:
   - "**/*agent*"
@@ -13,37 +13,38 @@ paths:
 
 # TheoKit Agents & Tools
 
-## Two Streaming Surfaces — pick one per endpoint
+## Server Surface — agents/*.ts (zero-config convention)
 
-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)
+Create an `agents/<name>.ts` file at the project root. It is automatically served at
+`POST /api/agents/<name>` (dev + build) with no manual route wiring.
 
 ```typescript
-// 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 }
-  },
+// agents/chat.ts
+import { defineAgent } from '@theokit/agents'
+import { z } from 'zod'
+
+export default defineAgent({
+  input: z.object({ message: z.string() }),
+  model: 'openai/gpt-4o-mini',
+  system: 'You are a helpful assistant.',
 })
 ```
 
-### Surface 2: Decorator (@Agent)
+The endpoint streams the ai-sdk `UIMessageStream` that `useAgent` (client hook) consumes.
+`@theokit/sdk` runs the agent; conversation turns auto-persist per session — the SDK owns storage.
+
+**Provider resolution:** `OPENROUTER_API_KEY` (preferred — routes to many models) OR
+`ANTHROPIC_API_KEY` / `OPENAI_API_KEY`. Set one in `.env`.
+
+## Advanced Surface — @Agent Decorator (DI / class-based)
+
+When you need dependency injection or class-based composition, use the `@Agent` class
+decorator from `@theokit/agents`. The class name determines the route:
+`AssistantAgent` → `POST /api/agents/assistant`.
 
 ```typescript
 // server/agents/assistant.agent.ts
-import { Agent, MainLoop, Tool, Toolbox } from '@theokit/agents'
+import { Agent, MainLoop } from '@theokit/agents'
 
 @Agent({
   model: 'openai/gpt-4o-mini',
@@ -57,9 +58,33 @@ export class AssistantAgent {
 }
 ```
 
-Convention: `AssistantAgent` → `POST /api/agents/assistant`
+## Tools — defineAgentTool
 
-## @Tool Decorator
+Declare typed tools with `defineAgentTool` (from `theokit/server`) and pass them to
+`defineAgent`'s `tools` array.
+
+```typescript
+// agents/chat.ts
+import { defineAgent } from '@theokit/agents'
+import { defineAgentTool } from 'theokit/server'
+import { z } from 'zod'
+
+const currentTimeTool = defineAgentTool({
+  name: 'current_time',
+  description: 'Return the current ISO timestamp',
+  inputSchema: z.object({}),
+  handler: async () => new Date().toISOString(),
+})
+
+export default defineAgent({
+  input: z.object({ message: z.string() }),
+  model: 'openai/gpt-4o-mini',
+  system: 'You are a helpful assistant.',
+  tools: [currentTimeTool],
+})
+```
+
+### @Tool Decorator (advanced / class-based)
 
 ```typescript
 import { Toolbox, Tool } from '@theokit/agents'
@@ -78,23 +103,26 @@ export class TaskTools {
 }
 ```
 
-## Client — useAgentStream (React hook)
-
-Works with BOTH surfaces. Transport: `fetch` POST + `ReadableStream` (SSE).
+## Client — useAgent (React hook)
 
 ```typescript
-import { useAgentStream } from 'theokit/client'
+import { useAgent } from 'theokit/client'
 
 function ChatUI() {
-  const { status, events, send, reset } = useAgentStream('/api/agents/assistant')
+  const { messages, status, send, reset } = useAgent<{ message: string }>('/api/agents/chat')
 
   return (
     <div>
       {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>}
+      {messages.map(message => (
+        <div key={message.id}>
+          {message.parts.map((part, i) => (
+            part.type === 'text'
+              ? <p key={i}>{part.text}</p>
+              : part.type === 'dynamic-tool'
+                ? <p key={i}>Using tool: {part.toolName}</p>
+                : null
+          ))}
         </div>
       ))}
       <button onClick={() => send({ message: 'Hello' })}>Send</button>
@@ -103,15 +131,23 @@ function ChatUI() {
 }
 ```
 
-### Non-React: consumeAgentStream
+`messages` is `UIMessage[]` (ai-sdk). Render `message.parts` — text parts
+(`part.type === 'text'`, `part.text`) and tool parts (`part.type === 'dynamic-tool'`,
+`part.toolName`, `part.state`, `part.output`). Do NOT switch on an `events`/`event.type`
+pattern — the wire is `UIMessageStream`, not SSE events.
+
+### Non-React: consumeUIMessageStream
 
 ```typescript
-import { consumeAgentStream } from 'theokit/client'
+import { consumeUIMessageStream } from 'theokit/client'
 
-const stream = consumeAgentStream('/api/agents/assistant', { body: { message: 'Hi' } })
-for await (const event of stream) {
-  console.log(event.type, event.content)
-}
+const response = await fetch('/api/agents/chat', {
+  method: 'POST',
+  body: JSON.stringify({ message: 'Hello' }),
+})
+consumeUIMessageStream(response, (message) => {
+  console.log(message.parts)
+})
 ```
 
 ## SDK Ecosystem — "you are here" map
@@ -121,7 +157,7 @@ Before writing custom tools, check if they already exist:
 | Package | What it provides | When to use |
 |---------|-----------------|-------------|
 | `@theokit/sdk` | `Agent.create()`, `defineTool()` (primitive), `Run.stream()` | Core agent runtime — always installed |
-| `@theokit/sdk-tools` | Ready-made tools: `createReadFileTool`, `createWriteFileTool`, `createSearchTool`, etc. | **Check here FIRST** before writing custom tools for coding agents |
+| `@theokit/sdk-tools` | Ready-made tools: `createReadFileTool`, `createWriteFileTool`, `createSearchTextTool`, `createGlobTool`, `createShellTool`, etc. | **Check here FIRST** before writing custom tools for coding agents |
 | `@theokit/di-agent` | DI-powered agent with decorator injection | When using dependency injection pattern |
 | `@theokit/di` | Core DI container (`@Injectable`, `@Inject`) | When `@theokit/di-agent` needs explicit bindings |
 
@@ -134,14 +170,12 @@ Before writing custom tools, check if they already exist:
 - `@UseGuards()` works on agents (shared with HTTP pipeline)
 - `@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
 - Check `@theokit/sdk-tools` BEFORE writing custom tools — it may already exist
 
 ## Anti-patterns
 
-- NEVER call OpenAI/Anthropic/OpenRouter APIs directly — use @Agent or defineAgentEndpoint
+- NEVER call OpenAI/Anthropic/OpenRouter APIs directly — use `defineAgent` or `@Agent`
 - NEVER reimplement tool calling loop — the SDK handles it
 - NEVER reimplement file/search/shell tools — use `@theokit/sdk-tools` (readFile, writeFile, search, etc.)
-- NEVER store conversations manually — use @Memory (decorator) or SDK persistence
+- NEVER store conversations manually — SDK persistence is automatic (the SDK owns storage)
 - 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

@@ -1,6 +1,6 @@
 ---
 name: theokit-frontend
-description: TheoKit frontend — file-based routing, layouts, theoFetch typed client, useAgentStream, React patterns
+description: TheoKit frontend — file-based routing, layouts, theoFetch typed client, useAgent, React patterns
 user-invocable: false
 paths:
   - "app/**"
@@ -50,23 +50,24 @@ const created = await client.tasks.POST({ body: { title: 'New' } })
 
 ## Agent Streaming
 
-Three client APIs, all from `theokit/client`:
+Two client APIs from `theokit/client`:
 
-### useAgentStream (React hook — most common)
+### useAgent (React hook — most common)
 
 ```typescript
-import { useAgentStream } from 'theokit/client'
+import { useAgent } from 'theokit/client'
 
 function ChatUI() {
-  const { status, events, send, reset } = useAgentStream('/api/agents/assistant')
+  const { messages, status, send, reset } = useAgent<{ message: string }>('/api/agents/chat')
 
   return (
     <div>
       {status === 'streaming' && <p>Thinking...</p>}
-      {events.map(event => (
-        <div key={event.id}>
-          {event.type === 'message' && <p>{event.content}</p>}
-          {event.type === 'tool_call' && <p>Using tool: {event.name}</p>}
+      {messages.map(message => (
+        <div key={message.id}>
+          {message.parts.map((part, i) =>
+            part.type === 'text' ? <p key={i}>{part.text}</p> : null
+          )}
         </div>
       ))}
       <button onClick={() => send({ message: 'Hello' })}>Send</button>
@@ -75,26 +76,23 @@ function ChatUI() {
 }
 ```
 
-### consumeAgentStream (non-React, async iterable)
+`messages` is `UIMessage[]` (ai-sdk). Render `message.parts`: text parts
+(`part.type === 'text'`, `part.text`) and tool parts (`part.type === 'dynamic-tool'`,
+`part.toolName`, `part.state`, `part.output`). Do NOT switch on an `events`/`event.type`
+pattern — the wire is `UIMessageStream`, not SSE events.
 
-```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)
+### consumeUIMessageStream (non-React)
 
 ```typescript
-import { parseSSEChunk } from 'theokit/client'
+import { consumeUIMessageStream } from 'theokit/client'
 
-// Parse a single SSE line into an AgentEvent (or null)
-const event = parseSSEChunk('data: {"type":"message","content":"Hello"}')
+const response = await fetch('/api/agents/chat', {
+  method: 'POST',
+  body: JSON.stringify({ message: 'Hello' }),
+})
+consumeUIMessageStream(response, (message) => {
+  console.log(message.parts)
+})
 ```
 
 ## Path Aliases
@@ -111,4 +109,4 @@ Configured in `tsconfig.json` — works in both server and app code.
 - 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
+- NEVER use `useEffect` + `fetch` for data loading — use theoFetch or `useAgent`