create-theokit 1.0.14 → 1.0.16

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',
+  input: z.object({}),
+  execute: async () => ({ time: 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
@@ -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`

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/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,34 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "theokit": "^0.5.4",
+    "theokit": "^0.15.1",
+    "@theokit/agents": "^0.30.1",
+    "@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",
     "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/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", "agents/**/*.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"
+  }
+}