create-theokit 1.0.14 → 1.0.16

package/templates/default/README.md.tmpl

@@ -1,6 +1,10 @@
 # {{name}}
 
-Built with [TheoKit](https://theokit.dev) — Build the app your agent lives in.
+Built with [TheoKit](https://theokit.dev) — **Build the app your agent lives in.**
+
+This is the default template: a working **agent chat surface** wired to a mock
+streaming agent, ready for you to plug in your LLM. Run it and you immediately
+see your agent talking — that's the point.
 
 ## Getting Started
 
@@ -8,75 +12,60 @@ Built with [TheoKit](https://theokit.dev) — Build the app your agent lives in.
 # Install dependencies
 npm install
 
-# Seed the database with sample data
-npm run seed
-
-# Start development server
+# Start development server (HMR)
 npm run dev
 ```
 
+Open the app and chat with the agent. Edit the agent at `agents/chat.ts`
+(pick your model / add tools) — the `@theokit/sdk` runtime resolves OpenRouter /
+Anthropic / Ollama / OpenAI from env vars (see the file's header comment).
+
 ## Project Structure
 
 ```
 {{name}}/
 ├── app/
-│   ├── page.tsx              # React frontend
-│   ├── layout.tsx            # Root layout
-│   └── globals.css           # Global styles
+│   ├── page.tsx              # Chat surface (@theokit/ui: ChatThread, ChatComposer, …)
+│   └── layout.tsx            # Root layout
 ├── server/
-│   ├── routes/
-│   │   ├── health.ts         # GET /api/health
-│   │   └── tasks/
-│   │       ├── index.ts      # GET /api/tasks + POST /api/tasks
-│   │       └── [id].ts       # GET/PUT/DELETE /api/tasks/:id
-│   ├── db/
-│   │   ├── schema.ts         # Drizzle ORM schema (SQLite)
-│   │   ├── index.ts          # DB connection + auto-create tables
-│   │   └── seed.ts           # Seed data
-│   └── index.ts              # Server barrel (routes auto-discovered)
-├── tests/
-│   └── tasks.test.ts         # API smoke test
+│   └── routes/
+│       ├── chat.ts           # Streaming agent endpoint (mock — replace with your LLM)
+│       └── health.ts         # GET /api/health
+├── tailwind.config.ts        # TheoUI design tokens
 ├── theo.config.ts            # TheoKit configuration
 └── .env.example              # Environment variables
 ```
 
-## API Endpoints
+## Key Concepts
 
-| Method | Path | Description |
-|--------|------|-------------|
-| GET | /api/tasks | List all tasks |
-| GET | /api/tasks/:id | Get task by ID |
-| POST | /api/tasks | Create task |
-| PUT | /api/tasks/:id | Update task |
-| DELETE | /api/tasks/:id | Delete task |
-| GET | /api/health | Health check |
+- **Agent chat surface** — `app/page.tsx` renders `@theokit/ui` chat components
+  driven by the streaming endpoint.
+- **`agents/chat.ts` (`defineAgent`)** — one file auto-served at `POST /api/agents/chat`,
+  streaming the ai-sdk `UIMessageStream` wire; `useAgent('/api/agents/chat')` on the client
+  reconstructs `UIMessage[]` you render via `message.parts`. `@theokit/sdk` owns
+  conversation persistence and provider resolution.
+- **`defineAgentTool`** — declare typed tools (the template ships a
+  `current_time` example).
 
-## Examples
+## About `@theokit/sdk`
 
-```bash
-# List tasks
-curl http://localhost:3000/api/tasks
+`@theokit/sdk` is the agent runtime this template depends on. Its publish to the
+public npm registry is **operator-deferred** — if `npm install` cannot resolve
+it yet, scaffold the registry-free variant instead (see Bare mode below) and add
+the SDK once it is published.
 
-# Create a task
-curl -X POST http://localhost:3000/api/tasks \
-  -H "Content-Type: application/json" \
-  -d '{"title":"New task","priority":"high"}'
+## Bare mode (`--bare`)
 
-# Update a task
-curl -X PUT http://localhost:3000/api/tasks/1 \
-  -H "Content-Type: application/json" \
-  -d '{"done":true}'
+Want the minimal "Hello Theo" scaffold with **no** agent UI and **no** unpublished
+registry dependencies? Scaffold with `--bare`:
 
-# Delete a task
-curl -X DELETE http://localhost:3000/api/tasks/1
+```bash
+npm create theokit my-app -- --template=default --bare
 ```
 
-## Key Concepts
-
-- **defineRoute** — Typed API routes with Zod validation
-- **Drizzle + SQLite** — Type-safe database, zero config
-- **File-based routing** — `server/routes/tasks/[id].ts` → `/api/tasks/:id`
-- **Seeds** — `npm run seed` loads sample data
+`--bare` strips `@theokit/ui`, `@theokit/sdk`, `lucide-react`, and the Tailwind
+toolchain, replaces `app/page.tsx` with a plain "Hello Theo" page, and removes
+the mock chat route — a scaffold that always installs without registry access.
 
 ## Commands
 
@@ -85,7 +74,6 @@ npm run dev          # Start dev server with HMR
 npm run build        # Build for production
 npm run start        # Run production build
 npm run test         # Run tests (vitest)
-npm run seed         # Seed database
 npm run lint         # ESLint check
 npm run typecheck    # TypeScript type check
 ```

package/templates/default/agents/chat.ts

@@ -0,0 +1,22 @@
+import { defineAgent } from '@theokit/agents'
+import { z } from 'zod'
+
+/**
+ * Chat agent — the zero-config `agents/*.ts` convention.
+ *
+ * This one file is auto-served at `POST /api/agents/chat` (dev + build), streaming the
+ * ai-sdk `UIMessageStream` that `useAgent('chat')` consumes on the client. No manual route,
+ * no manual client wiring. `@theokit/sdk` runs it; conversation turns auto-persist per
+ * session (the SDK owns storage).
+ *
+ * Provider: resolved from the environment — OPENROUTER_API_KEY (preferred — gateway to many
+ * models) OR ANTHROPIC_API_KEY / OPENAI_API_KEY. The `model` id is prefixed with the provider
+ * namespace so OpenRouter routes it upstream (see https://openrouter.ai/models).
+ *
+ * Add tools with `defineAgentTool` (from `theokit/server`) and pass them to `tools: [...]`.
+ */
+export default defineAgent({
+  input: z.object({ message: z.string() }),
+  model: 'openai/gpt-4o-mini',
+  system: 'You are a helpful assistant.',
+})

package/templates/default/app/layout.tsx

@@ -1,5 +1,73 @@
-import './globals.css'
+import '@theokit/ui/styles.css'
 
-export default function Layout({ children }: { children: React.ReactNode }) {
-  return <>{children}</>
+import { Outlet } from 'react-router'
+import { AgentProfile, ThemeSwitcher, CostMeter, type AgentProfileDescriptor } from '@theokit/ui'
+import { Sidebar, TopNav, Tooltip, Badge } from '@usetheo/ui'
+import { Bot, MessageSquare, History, Settings } from 'lucide-react'
+
+const AGENTS: AgentProfileDescriptor[] = [
+  {
+    id: 'theo',
+    name: 'Theo',
+    description: 'Edit the agent at agents/chat.ts.',
+    tone: 'primary',
+    initials: 'TH',
+    badge: 'Online',
+  },
+]
+
+export default function RootLayout() {
+  return (
+    <div className="grid h-screen w-screen grid-rows-[auto_1fr] bg-background text-foreground">
+      <TopNav className="border-border/60 border-b px-4 py-2">
+        <TopNav.Left>
+          <Tooltip label="TheoKit agent surface" side="bottom">
+            <span className="inline-flex items-center gap-2">
+              <Bot className="size-5 text-primary" aria-hidden />
+              <span className="font-semibold text-sm tracking-tight">Theo Agent</span>
+              <Badge variant="outline" size="sm">
+                v0.1
+              </Badge>
+            </span>
+          </Tooltip>
+        </TopNav.Left>
+        <TopNav.Right>
+          <Tooltip label="Toggle theme" side="bottom" align="end">
+            <span>
+              <ThemeSwitcher />
+            </span>
+          </Tooltip>
+        </TopNav.Right>
+      </TopNav>
+
+      <div className="grid h-full grid-cols-[260px_1fr] overflow-hidden">
+        <Sidebar className="flex flex-col border-border/60 border-r p-3">
+          <Sidebar.Header>
+            <AgentProfile agents={AGENTS} activeId="theo" />
+          </Sidebar.Header>
+
+          <Sidebar.Section title="Workspace">
+            <Sidebar.Item icon={MessageSquare} active>
+              New conversation
+            </Sidebar.Item>
+            <Sidebar.Item icon={History}>History</Sidebar.Item>
+            <Sidebar.Item icon={Settings}>Settings</Sidebar.Item>
+          </Sidebar.Section>
+
+          <Sidebar.Footer className="mt-auto">
+            <CostMeter
+              compact
+              title="This session"
+              cost={0.0023}
+              delta={{ value: 0.0023, period: 'now' }}
+            />
+          </Sidebar.Footer>
+        </Sidebar>
+
+        <main className="flex h-full flex-col overflow-hidden">
+          <Outlet />
+        </main>
+      </div>
+    </div>
+  )
 }

package/templates/default/app/page.tsx

@@ -1,68 +1,303 @@
+'use client'
+
+import { useEffect, useMemo, useState } from 'react'
+import {
+  ChatThread,
+  ChatMessage,
+  ChatComposer,
+  ToolCallCard,
+  AgentStreaming,
+  AgentErrorCard,
+  QuickActionChips,
+  ContextWindowBar,
+  type Message,
+  type QuickAction,
+  type ToolCallStatus,
+} from '@theokit/ui'
+import {
+  EmptyState,
+  CommandPalette,
+  Avatar,
+  Tooltip,
+  Button,
+  ScrollArea,
+  type CommandItem,
+} from '@usetheo/ui'
+import { Sparkles, Wrench, RotateCcw, Command } from 'lucide-react'
+import { useAgent } from 'theokit/client'
+
+/**
+ * Default scaffold — an Agent Surface, composed entirely from TheoUI.
+ *
+ *   ChatThread / ChatMessage  → conversation
+ *   ToolCallCard              → expandable tool invocations
+ *   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
+ *   Tooltip                   → hints on icons
+ *
+ * `useAgent` binds to the `agents/chat.ts` endpoint, consumes the ai-sdk
+ * `UIMessageStream`, and handles AbortController cleanup + StrictMode safety.
+ * 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 },
+  { id: 'reset', label: 'Start a new conversation', icon: RotateCcw },
+]
+
+const COMMAND_ITEMS: CommandItem[] = QUICK_ACTIONS.map((a) => ({
+  id: a.id,
+  label: a.label,
+  icon: a.icon,
+  group: 'Quick actions',
+}))
+
+// 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 = 'gpt-4o-mini'
+
+const ASSISTANT_AVATAR = (
+  <Avatar size="sm" tone="primary">
+    <Avatar.Fallback>TH</Avatar.Fallback>
+  </Avatar>
+)
+const USER_AVATAR = (
+  <Avatar size="sm" tone="muted">
+    <Avatar.Fallback>YOU</Avatar.Fallback>
+  </Avatar>
+)
+
 export default function Page() {
+  const [composerValue, setComposerValue] = useState('')
+  const [userMessages, setUserMessages] = useState<ConversationItem[]>([])
+  const [paletteOpen, setPaletteOpen] = useState(false)
+  const { messages, send, status, reset } = useAgent<{ message: string }>('/api/agents/chat')
+
+  // ⌘K / Ctrl+K opens the CommandPalette.
+  useEffect(() => {
+    function onKey(e: KeyboardEvent) {
+      if ((e.metaKey || e.ctrlKey) && e.key === 'k') {
+        e.preventDefault()
+        setPaletteOpen((v) => !v)
+      }
+    }
+    window.addEventListener('keydown', onKey)
+    return () => window.removeEventListener('keydown', onKey)
+  }, [])
+
+  // Derive the conversation view from the reconstructed assistant UIMessages
+  // (ai-sdk `UIMessageStream`): text parts → messages, tool parts → tool cards.
+  const items = useMemo<ConversationItem[]>(() => {
+    const ts = new Date().toISOString()
+    const agentItems: ConversationItem[] = []
+    for (const message of messages) {
+      if (message.role !== 'assistant') continue
+      message.parts.forEach((part, i) => {
+        const id = `${message.id}-${i}`
+        if (part.type === 'text') {
+          agentItems.push({
+            kind: 'message',
+            id,
+            role: 'assistant',
+            content: part.text,
+            timestamp: ts,
+          })
+        } else if (part.type === 'dynamic-tool') {
+          agentItems.push({
+            kind: 'tool',
+            id,
+            tool: part.toolName,
+            target:
+              part.input && typeof part.input === 'object'
+                ? Object.entries(part.input as Record<string, unknown>)
+                    .map(([k, v]) => `${k}=${JSON.stringify(v)}`)
+                    .join(' ')
+                : undefined,
+            status:
+              part.state === 'output-available'
+                ? 'success'
+                : part.state === 'output-error'
+                  ? 'error'
+                  : 'running',
+            output:
+              part.state === 'output-available'
+                ? typeof part.output === 'string'
+                  ? part.output
+                  : JSON.stringify(part.output, null, 2)
+                : part.state === 'output-error'
+                  ? part.errorText
+                  : undefined,
+            timestamp: ts,
+          })
+        }
+      })
+    }
+    return [...userMessages, ...agentItems]
+  }, [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() },
+    ])
+    send({ message: trimmed })
+    setComposerValue('')
+  }
+
+  function handleQuickAction(id: string) {
+    setPaletteOpen(false)
+    if (id === 'reset') {
+      setUserMessages([])
+      reset()
+      return
+    }
+    const action = QUICK_ACTIONS.find((a) => a.id === id)
+    if (action) handleSubmit(action.label)
+  }
+
+  const isStreaming = status === 'streaming'
+  const isEmpty = items.length === 0 && !isStreaming
+  const hasError = status === 'error'
+
   return (
-    <div className="page">
-      <div className="main">
-        <header className="hero">
-          <img src="/logo.png" alt="TheoKit" width={72} height={72} className="hero-logo" />
-          <h1>TheoKit</h1>
-          <p className="tagline">Build the app your agent lives in.</p>
-          <nav className="ctas">
-            <a
-              href="https://usetheo.dev"
-              target="_blank"
-              rel="noopener noreferrer"
-              className="btn primary"
-            >
-              Get Started
-            </a>
-            <a
-              href="https://github.com/usetheodev/theokit"
-              target="_blank"
-              rel="noopener noreferrer"
-              className="btn secondary"
-            >
-              Documentation
-            </a>
-          </nav>
-          <p className="hint">
-            Edit <code>app/page.tsx</code> to get started. Changes hot-reload instantly.
-          </p>
-        </header>
-
-        <div className="grid features">
-          <div className="feature">
-            <h3>defineRoute</h3>
-            <p>
-              Typed API routes with Zod validation. See <code>server/routes/</code>
-            </p>
-          </div>
-          <div className="feature">
-            <h3>Drizzle + SQLite</h3>
-            <p>
-              Type-safe database with zero config. Schema in <code>server/db/schema.ts</code>
-            </p>
-          </div>
-          <div className="feature">
-            <h3>@Agent + @Tool</h3>
-            <p>AI agents with SSE streaming, budget control, and human-in-the-loop approval.</p>
-          </div>
-          <div className="feature">
-            <h3>React + Vite</h3>
-            <p>File-based routing, HMR, SSR streaming. Edit and see changes instantly.</p>
-          </div>
+    <>
+      <ContextWindowBar
+        used={CONTEXT_USED}
+        total={CONTEXT_TOTAL}
+        trailing={MODEL_NAME}
+        label="Context window"
+        compact
+        className="border-border/60 border-b px-6 py-2"
+      />
+
+      <ScrollArea className="flex-1">
+        <div className="mx-auto flex w-full max-w-3xl flex-col gap-4 px-6 py-6">
+          {isEmpty ? (
+            <EmptyState
+              eyebrow="Theo Agent"
+              icon={Sparkles}
+              title="What should we build today?"
+              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}
+                  />
+                )
+              })}
+              {isStreaming && <AgentStreaming model={MODEL_NAME} />}
+            </ChatThread>
+          )}
         </div>
+      </ScrollArea>
 
-        <footer className="footer">
-          Powered by{' '}
-          <a href="https://usetheo.dev" target="_blank" rel="noopener noreferrer">
-            TheoKit
-          </a>
-          {' · '}
-          <a href="https://github.com/usetheodev/theokit" target="_blank" rel="noopener noreferrer">
-            GitHub
-          </a>
-        </footer>
+      <div className="border-border/60 border-t bg-background/50 backdrop-blur">
+        <div className="mx-auto w-full max-w-3xl px-6 py-4">
+          {hasError && (
+            <div className="mb-3">
+              <AgentErrorCard
+                kind="network"
+                title="Stream ended with an error"
+                description="The connection to the agent endpoint was interrupted. Reset to try again."
+                action={
+                  <Button variant="ghost" size="sm" onClick={() => reset()}>
+                    Reset
+                  </Button>
+                }
+              />
+            </div>
+          )}
+          <ChatComposer
+            value={composerValue}
+            onValueChange={setComposerValue}
+            onSubmit={handleSubmit}
+            running={isStreaming}
+            placeholder="Ask the agent…"
+            leadingActions={
+              <Tooltip label="Open command palette (⌘K)" side="top">
+                <Button
+                  type="button"
+                  variant="ghost"
+                  size="icon"
+                  onClick={() => setPaletteOpen(true)}
+                  aria-label="Open command palette"
+                >
+                  <Command className="size-4" />
+                </Button>
+              </Tooltip>
+            }
+          />
+        </div>
       </div>
-    </div>
+
+      <CommandPalette
+        open={paletteOpen}
+        onOpenChange={setPaletteOpen}
+        items={COMMAND_ITEMS}
+        onSelect={handleQuickAction}
+        placeholder="Run a command…"
+        emptyMessage="No matching commands."
+      />
+    </>
   )
 }