create-theokit 1.0.13 → 1.0.15

package/templates/default/app/page.tsx

@@ -1,68 +1,288 @@
+'use client'
+
+import { useEffect, useMemo, useState } from 'react'
+import {
+  ChatThread,
+  ChatMessage,
+  ChatComposer,
+  ToolCallCard,
+  AgentStreaming,
+  AgentErrorCard,
+  EmptyState,
+  QuickActionChips,
+  ContextWindowBar,
+  CommandPalette,
+  Avatar,
+  Tooltip,
+  Button,
+  ScrollArea,
+  type Message,
+  type QuickAction,
+  type CommandItem,
+  type ToolCallStatus,
+} from '@theokit/ui'
+import { Sparkles, Wrench, RotateCcw, Command } from 'lucide-react'
+import { useAgentStream } 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
+ *
+ * `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).
+ */
+
+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',
+}))
+
+// Mock context-window usage — replace with real model state.
+const CONTEXT_USED = 4_200
+const CONTEXT_TOTAL = 200_000
+const MODEL_NAME = 'mock-llm'
+
+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 { events, send, status, reset } = useAgentStream<{ message: string }>('/api/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)
+  }, [])
+
+  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])
+
+  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 with a mock LLM at server/routes/chat.ts so you can see the wiring before plugging in a real model."
+              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."
+      />
+    </>
   )
 }

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

@@ -114,6 +114,19 @@ for await (const event of stream) {
 }
 ```
 
+## SDK Ecosystem — "you are here" map
+
+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/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 |
+
+**`defineTool()` in `@theokit/sdk` is the primitive API.** For coding agents, `@theokit/sdk-tools` has batteries-included tools that wrap `defineTool()` with file system access, search, shell execution, etc. Don't reimplement what `sdk-tools` already provides.
+
 ## Rules
 
 - Tool `name` and `description` are ALWAYS explicit — never inferred from method names (G4)
@@ -122,11 +135,13 @@ for await (const event of stream) {
 - `@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 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 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/eslint.config.mjs

@@ -1,18 +1,14 @@
 import tseslint from 'typescript-eslint'
 import prettierConfig from 'eslint-config-prettier'
-import drizzle from 'eslint-plugin-drizzle'
 
 export default tseslint.config(
-  { ignores: ['dist/', 'node_modules/', 'drizzle/'] },
+  { ignores: ['dist/', 'node_modules/'] },
   ...tseslint.configs.recommended,
   prettierConfig,
   {
-    plugins: { drizzle },
     rules: {
       '@typescript-eslint/no-unused-vars': ['warn', { argsIgnorePattern: '^_' }],
       '@typescript-eslint/no-explicit-any': 'warn',
-      'drizzle/enforce-delete-with-where': 'error',
-      'drizzle/enforce-update-with-where': 'error',
     },
   },
 )

package/templates/default/package.json.tmpl

@@ -8,8 +8,6 @@
     "build": "theokit build",
     "start": "theokit start",
     "test": "vitest run",
-    "db:migrate": "theokit db migrate",
-    "db:generate": "theokit db generate",
     "lint": "eslint .",
     "lint:fix": "eslint . --fix",
     "format": "prettier --write .",
@@ -17,25 +15,28 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "theokit": "^0.5.4",
+    "theokit": "^0.6.0",
+    "@theokit/sdk": "^1.1.0",
+    "@theokit/ui": "^0.14.0",
+    "lucide-react": "^0.469.0",
     "react": "^19.0.0",
     "react-dom": "^19.0.0",
     "react-router": "^7.0.0",
-    "zod": "^4.0.0",
-    "drizzle-orm": "^0.44.0",
-    "better-sqlite3": "^12.0.0"
+    "zod": "^4.0.0"
   },
   "devDependencies": {
-    "@types/better-sqlite3": "^7.6.0",
     "@types/react": "^19.0.0",
     "@types/react-dom": "^19.0.0",
-    "drizzle-kit": "^0.30.0",
+    "tailwindcss": "^4.0.0",
+    "@tailwindcss/vite": "^4.0.0",
     "eslint": "^9.0.0",
     "eslint-config-prettier": "^10.0.0",
-    "eslint-plugin-drizzle": "^0.2.0",
     "prettier": "^3.0.0",
     "typescript": "^5.5.0",
     "typescript-eslint": "^8.0.0",
     "vitest": "^3.0.0"
+  },
+  "pnpm": {
+    "onlyBuiltDependencies": ["esbuild", "better-sqlite3", "workerd"]
   }
 }

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

@@ -0,0 +1,69 @@
+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}` }
+    }
+  },
+})

package/templates/default/theo.config.ts

@@ -1,5 +1,3 @@
 import { defineConfig } from 'theokit'
 
-export default defineConfig({
-  port: 3000,
-})
+export default defineConfig({})

package/templates/default/tsconfig.json

@@ -1,22 +1,15 @@
 {
   "compilerOptions": {
     "target": "ES2022",
-    "module": "NodeNext",
-    "moduleResolution": "NodeNext",
-    "experimentalDecorators": true,
-    "emitDecoratorMetadata": true,
+    "module": "ESNext",
+    "moduleResolution": "bundler",
     "strict": true,
-    "jsx": "react-jsx",
+    "noEmit": true,
     "esModuleInterop": true,
     "skipLibCheck": true,
-    "outDir": "dist",
-    "baseUrl": ".",
-    "paths": {
-      "@/*": ["./*"],
-      "@/server/*": ["./server/*"],
-      "@/app/*": ["./app/*"]
-    }
+    "jsx": "react-jsx",
+    "isolatedModules": true,
+    "resolveJsonModule": true
   },
-  "include": ["**/*.ts", "**/*.tsx"],
-  "exclude": ["node_modules", "dist"]
+  "include": ["app/**/*.ts", "app/**/*.tsx", "server/**/*.ts"]
 }

package/templates/default/types/jobs.d.ts

@@ -0,0 +1,25 @@
+/**
+ * JobRegistry augmentation — REQUIRED for typed `ctx.queue.enqueue` calls.
+ *
+ * Without this augmentation, `ctx.queue.enqueue('foo', ...)` errors with:
+ *   "Type 'foo' is not assignable to type 'never'"
+ *
+ * This is the canonical TheoKit jobs onboarding bug (EC-110). To add a
+ * job:
+ *
+ * 1. Create `server/jobs/<name>.ts` exporting `defineJob('<name>', ...)`
+ * 2. Add `'<name>': { ...inputShape }` below
+ * 3. Use `ctx.queue.enqueue('<name>', { ...input })` from any route handler
+ *
+ * See: docs/concepts/jobs.md
+ */
+declare module 'theokit/server' {
+  interface JobRegistry {
+    // Add your jobs here. Examples (uncomment and customize):
+    //
+    // 'process-document': { documentId: string }
+    // 'send-email': { to: string; subject: string; body: string }
+  }
+}
+
+export {}

package/templates/services/agent-node/Dockerfile.tmpl

@@ -0,0 +1,20 @@
+FROM node:22-alpine
+
+WORKDIR /app
+
+# Install pnpm (or use npm if pnpm not available in image)
+RUN corepack enable && corepack prepare pnpm@latest --activate || true
+
+# Copy manifest and install
+COPY package.json ./
+RUN pnpm install --frozen-lockfile || npm install
+
+# Copy source
+COPY . .
+
+EXPOSE 8002
+
+HEALTHCHECK --interval=10s --timeout=5s --retries=3 \
+    CMD wget --spider -q http://localhost:8002/health || exit 1
+
+CMD ["pnpm", "start"]

package/templates/services/agent-node/README.md

@@ -0,0 +1,38 @@
+# Agent service (Node / Hono)
+
+This is a TheoKit polyglot sidecar generated by `create-theokit --backend node`.
+
+## Requirements
+
+- **Node.js 22+** (matches TheoKit's floor)
+- **pnpm** or **npm** (TheoKit's CLI prefers pnpm)
+
+## Run it
+
+The TheoKit app boots this service automatically via `pnpm dev` (per `theo.config.ts > services`).
+
+To run standalone:
+
+```bash
+cd services/agent-node
+pnpm install
+pnpm dev
+```
+
+## Endpoints
+
+- `GET /health` — healthcheck (returns `{"status":"ok"}`)
+- `POST /echo` — example: `{ "message": "..." }` → `{ "echo": "..." }`
+
+## What is wired
+
+- Native fetch handler via Hono (works on TheoCloud and local)
+- JSON-line stdout logs
+- W3C `traceparent` propagation from incoming headers
+- TheoKit injects `THEOKIT_SERVICE_NAME` + `THEOKIT_SERVICE_PORT` env vars
+
+## Add a tool the TheoKit agent can call
+
+Add another `app.post('/tool/<name>', ...)` handler. From the TheoKit TS side,
+`services.worker.<name>({...})` is auto-typed when an OpenAPI URL is reachable
+(Hey API integration — Phase 5).

package/templates/services/agent-node/package.json.tmpl

@@ -0,0 +1,18 @@
+{
+  "name": "{{name}}-agent-node",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "tsx watch src/index.ts",
+    "start": "tsx src/index.ts",
+    "build": "echo 'no build step; tsx runs TS directly'"
+  },
+  "dependencies": {
+    "hono": "^4.6.0",
+    "@hono/node-server": "^1.13.0"
+  },
+  "devDependencies": {
+    "tsx": "^4.19.0",
+    "typescript": "^5.7.0"
+  }
+}