create-theokit 1.0.15 → 1.0.17

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

@@ -1,6 +1,6 @@
 ---
 name: theokit-ui
-description: "@theokit/ui component library — chat UI (ChatThread, ChatMessage, ChatComposer, CodeBlock), theming, providers, sidebar"
+description: "@theokit/ui AI-native component library — AI-agent surfaces (ChatThread, ChatMessage, ChatComposer, ToolCallCard, AgentStream), theming, providers; generic primitives (CodeBlock, Sidebar, Button) come from @usetheo/ui"
 user-invocable: false
 paths:
   - "app/**"
@@ -12,13 +12,13 @@ paths:
   - "**/*Theme*"
 ---
 
-# @theokit/ui — AI Chat Component Library
+# @theokit/ui — AI-native Component Library (AI-agent surfaces)
 
-`@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.
+`@theokit/ui` is an optional peer dependency. If installed, it provides ready-made AI components for chat + coding-agent surfaces (chat thread, agent events, tool calls, diff viewer, build logs), plus theming. **Never build custom equivalents** of components it provides. Generic primitives (Button, Input, Card, CodeBlock, PageShell, Sidebar, Avatar, Alert, etc.) live in `@usetheo/ui`, which `@theokit/ui` depends on — import those from `@usetheo/ui`.
 
 ## Package Identity
 
-The published package is `@theokit/ui` (NOT `@usetheo/ui` — that was the old name).
+`@theokit/ui` (AI-native, currently `1.0.0`) provides the AI-agent-surface components. Its generic foundation was split into `@usetheo/ui` in the 2026-07-03 AI-exclusive pivot; `@theokit/ui` depends on `@usetheo/ui`, so installing `@theokit/ui` pulls the foundation transitively.
 
 ```bash
 # Install from npm (preferred)
@@ -54,19 +54,19 @@ export default function Layout({ children }) {
 ### Full Chat Page (typical assembly)
 
 ```typescript
+// AI-agent-surface components live in @theokit/ui
 import {
-  PageShell,
-  Sidebar,
-  SessionListItem,
   ChatThread,
   ChatMessage,
   ChatMessageContent,
   ChatComposer,
 } from '@theokit/ui'
-import { useAgentStream } from 'theokit/client'
+// Generic layout primitives moved to @usetheo/ui (2026-07-03 pivot)
+import { PageShell, Sidebar, SessionListItem } from '@usetheo/ui'
+import { useAgent } from 'theokit/client'
 
 function ChatPage() {
-  const { status, events, send } = useAgentStream('/api/agents/assistant')
+  const { messages, status, send } = useAgent('/api/agents/assistant')
 
   return (
     <PageShell sidebar={
@@ -77,9 +77,13 @@ function ChatPage() {
       </Sidebar>
     }>
       <ChatThread>
-        {messages.map(m => (
-          <ChatMessage key={m.id} role={m.role}>
-            <ChatMessageContent markdown={m.content} />
+        {messages.map(message => (
+          <ChatMessage key={message.id} role={message.role}>
+            {message.parts.map((part, i) =>
+              part.type === 'text'
+                ? <ChatMessageContent key={i} markdown={part.text} />
+                : null
+            )}
           </ChatMessage>
         ))}
       </ChatThread>
@@ -93,29 +97,29 @@ function ChatPage() {
 }
 ```
 
-### Individual Components
+### AI-agent-surface components (from `@theokit/ui`)
 
 | 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` |
+| `ToolCallCard` | Display agent tool invocations | — |
+| `AgentStream` | Lower-level stream renderer | — |
 
-### Other Useful Components
+### Generic primitives (from `@usetheo/ui`)
 
-| 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 |
+Moved out of `@theokit/ui` in the 2026-07-03 AI-exclusive pivot. Import these from `@usetheo/ui`.
+
+| Component | Purpose | Key Props |
+|-----------|---------|-----------|
+| `CodeBlock` | Syntax-highlighted code | `code: string`, `language?: string` (uses shiki, lazy-loaded) |
+| `PageShell` | App layout with sidebar slot | `sidebar?: ReactNode`, `children` |
+| `Sidebar` | Collapsible side panel | `children` |
+| `Button`, `Input`, `Textarea` | Form primitives (themed) | — |
+| `Avatar` | User/agent avatar | — |
+| `Alert` | Status messages | — |
 
 ## Peer Dependencies (install only what you use)
 
@@ -154,8 +158,8 @@ const myTheme = defineTheme({
 
 - 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 build a custom code highlighter — `CodeBlock` (from `@usetheo/ui`) uses shiki (lazy-loaded)
+- Import AI-agent-surface components (ChatThread, ChatMessage, ToolCallCard, etc.) from `@theokit/ui`; import generic primitives (Button, Input, CodeBlock, PageShell, Sidebar, Avatar, Alert) from `@usetheo/ui` — both are live packages since the 2026-07-03 pivot (`@theokit/ui` depends on `@usetheo/ui`)
 - NEVER use `npm link` or `file:../theo-ui` to install — causes dual-React (use tarball or npm registry)
 - NEVER install ALL peer deps — only install the peers for components you actually use
 - NEVER use components without wrapping in `TheoUIProvider` + `ThemeProvider` first

package/templates/default/package.json.tmpl

@@ -15,9 +15,11 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "theokit": "^0.6.0",
-    "@theokit/sdk": "^1.1.0",
-    "@theokit/ui": "^0.14.0",
+    "theokit": "^0.15.2",
+    "@theokit/agents": "^0.30.2",
+    "@theokit/sdk": "^2.13.0",
+    "@theokit/ui": "^1.0.0",
+    "@usetheo/ui": "^0.14.0",
     "lucide-react": "^0.469.0",
     "react": "^19.0.0",
     "react-dom": "^19.0.0",
@@ -25,8 +27,11 @@
     "zod": "^4.0.0"
   },
   "devDependencies": {
+    "@testing-library/react": "^16.0.0",
+    "@types/node": "^22.0.0",
     "@types/react": "^19.0.0",
     "@types/react-dom": "^19.0.0",
+    "jsdom": "^25.0.0",
     "tailwindcss": "^4.0.0",
     "@tailwindcss/vite": "^4.0.0",
     "eslint": "^9.0.0",
@@ -37,6 +42,10 @@
     "vitest": "^3.0.0"
   },
   "pnpm": {
-    "onlyBuiltDependencies": ["esbuild", "better-sqlite3", "workerd"]
+    "onlyBuiltDependencies": [
+      "esbuild",
+      "better-sqlite3",
+      "workerd"
+    ]
   }
 }

package/templates/default/tsconfig.json

@@ -9,7 +9,9 @@
     "skipLibCheck": true,
     "jsx": "react-jsx",
     "isolatedModules": true,
-    "resolveJsonModule": true
+    "resolveJsonModule": true,
+    "experimentalDecorators": true,
+    "emitDecoratorMetadata": true
   },
-  "include": ["app/**/*.ts", "app/**/*.tsx", "server/**/*.ts"]
+  "include": ["app/**/*.ts", "app/**/*.tsx", "server/**/*.ts", "agents/**/*.ts"]
 }

package/templates/default/server/routes/chat.ts

@@ -1,69 +0,0 @@
-import { z } from 'zod'
-import {
-  defineAgentEndpoint,
-  defineAgentTool,
-  streamAgentRun,
-  createConversationHistory,
-  type AgentEvent,
-} from 'theokit/server'
-
-/**
- * Chat agent endpoint — persistent conversation via createConversationHistory.
- *
- * Each browser tab gets a stable conversation id cookie on first visit;
- * subsequent requests resume the same agent. Conversation turns auto-persist
- * in `<cwd>/.theokit/agents/<conversationId>/messages.jsonl` (SDK owns
- * storage). Tools: current_time example. Memory facts: opt-in via
- * options.memory (off by default).
- *
- * Provider: OPENROUTER_API_KEY (preferred — gateway to many models) OR
- * ANTHROPIC_API_KEY (direct Anthropic).
- */
-
-const currentTime = defineAgentTool({
-  name: 'current_time',
-  description: 'Get the current ISO timestamp on the server.',
-  inputSchema: z.object({}),
-  handler: () => new Date().toISOString(),
-})
-
-export const POST = defineAgentEndpoint({
-  async *handler({ body, request, cookieHeaders, signal }): AsyncGenerator<AgentEvent> {
-    const safeBody =
-      body !== null && typeof body === 'object' && !Array.isArray(body)
-        ? (body as { message?: string })
-        : {}
-    const { message = '' } = safeBody
-    // Provider resolution centralizada (Strategy pattern) — theokit/server resolve
-    // apiKey + baseUrl + provider automático via OPENROUTER_API_KEY / OPENAI_API_KEY /
-    // ANTHROPIC_API_KEY presente no env. Wire protocol: OpenAI Chat Completions
-    // (universal — todos os providers implementam essa API). Consumer NÃO tem
-    // conditionals sobre provider — é responsabilidade do framework.
-    // Wrap full agent lifecycle in try/catch — provider errors (invalid KEY,
-    // 401, rate-limit, model-not-found, 5xx) MUST surface as AgentEvent
-    // 'error' so the client renders an actionable message instead of a
-    // silent SSE closure. Dogfood chaos Phase 12 validates this contract.
-    try {
-      const { agent } = await createConversationHistory({
-        request,
-        response: { headers: cookieHeaders },
-        options: {
-          // Model id is prefixed with the provider namespace. When using
-          // OPENROUTER_API_KEY (default), prefixes route to the correct
-          // upstream — `openai/`, `anthropic/`, `google/`, `meta-llama/`,
-          // `mistralai/`, `groq/`, etc. See https://openrouter.ai/models.
-          // Without the prefix the SDK falls back to a stub response.
-          model: { id: 'openai/gpt-4o-mini' },
-          tools: [currentTime],
-        },
-      })
-      const run = await agent.send(message, { signal })
-      yield* streamAgentRun(run)
-      // Intentionally NO agent.dispose() — the agent stays registered so the
-      // next request from the same conversation resumes it (continuity).
-    } catch (err) {
-      const msg = err instanceof Error ? err.message : String(err)
-      yield { type: 'error', message: `Agent error: ${msg}` }
-    }
-  },
-})