create-theokit 1.0.13 → 1.0.14
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/package.json
CHANGED
|
@@ -82,6 +82,19 @@ npx drizzle-kit push # Apply schema changes (dev)
|
|
|
82
82
|
npx drizzle-kit generate # Generate migration files (prod)
|
|
83
83
|
```
|
|
84
84
|
|
|
85
|
+
## SDK Ecosystem
|
|
86
|
+
|
|
87
|
+
| Package | Purpose | Install separately? |
|
|
88
|
+
|---------|---------|-------------------|
|
|
89
|
+
| `theokit` | Framework (routes, SSR, client, CLI) | Already installed |
|
|
90
|
+
| `@theokit/sdk` | Agent runtime (Agent.create, defineTool primitive) | Already installed |
|
|
91
|
+
| `@theokit/sdk-tools` | Ready-made tools (readFile, writeFile, search, shell) | Yes — `npm install @theokit/sdk-tools` |
|
|
92
|
+
| `@theokit/agents` | Decorator surface (@Agent, @Tool, @Toolbox) | Already installed |
|
|
93
|
+
| `@theokit/ui` | AI chat UI components (ChatThread, ChatComposer, CodeBlock) | Yes — `npm install @theokit/ui` |
|
|
94
|
+
| `@theokit/di-agent` | DI-powered agent pattern | Yes — when using DI |
|
|
95
|
+
|
|
96
|
+
**Before writing custom tools, check `@theokit/sdk-tools`** — it likely has what you need.
|
|
97
|
+
|
|
85
98
|
## Don't
|
|
86
99
|
|
|
87
100
|
- Don't use `any` — use Zod schemas + `z.infer<>`
|
|
@@ -89,3 +102,5 @@ npx drizzle-kit generate # Generate migration files (prod)
|
|
|
89
102
|
- Don't parse request body manually — use `body: z.object(...)` in defineRoute
|
|
90
103
|
- Don't import from `theokit/dist/...` or `theokit/src/...` — use public exports only
|
|
91
104
|
- Don't call LLM APIs directly — use @Agent + @Tool decorators
|
|
105
|
+
- Don't reimplement file/search/shell tools — use `@theokit/sdk-tools`
|
|
106
|
+
- Don't use `npm link` for `@theokit/ui` — causes dual-React; use tarball or npm registry
|
|
@@ -114,6 +114,19 @@ for await (const event of stream) {
|
|
|
114
114
|
}
|
|
115
115
|
```
|
|
116
116
|
|
|
117
|
+
## SDK Ecosystem — "you are here" map
|
|
118
|
+
|
|
119
|
+
Before writing custom tools, check if they already exist:
|
|
120
|
+
|
|
121
|
+
| Package | What it provides | When to use |
|
|
122
|
+
|---------|-----------------|-------------|
|
|
123
|
+
| `@theokit/sdk` | `Agent.create()`, `defineTool()` (primitive), `Run.stream()` | Core agent runtime — always installed |
|
|
124
|
+
| `@theokit/sdk-tools` | Ready-made tools: `createReadFileTool`, `createWriteFileTool`, `createSearchTool`, etc. | **Check here FIRST** before writing custom tools for coding agents |
|
|
125
|
+
| `@theokit/di-agent` | DI-powered agent with decorator injection | When using dependency injection pattern |
|
|
126
|
+
| `@theokit/di` | Core DI container (`@Injectable`, `@Inject`) | When `@theokit/di-agent` needs explicit bindings |
|
|
127
|
+
|
|
128
|
+
**`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.
|
|
129
|
+
|
|
117
130
|
## Rules
|
|
118
131
|
|
|
119
132
|
- Tool `name` and `description` are ALWAYS explicit — never inferred from method names (G4)
|
|
@@ -122,11 +135,13 @@ for await (const event of stream) {
|
|
|
122
135
|
- `@UseInterceptors()` and `@UseFilters()` on agents are metadata-only (emit warnings)
|
|
123
136
|
- Agent runtime is `@theokit/sdk` — NEVER call LLM APIs directly via fetch
|
|
124
137
|
- Pick ONE surface per endpoint — don't mix defineAgentEndpoint with @Agent for the same route
|
|
138
|
+
- Check `@theokit/sdk-tools` BEFORE writing custom tools — it may already exist
|
|
125
139
|
|
|
126
140
|
## Anti-patterns
|
|
127
141
|
|
|
128
142
|
- NEVER call OpenAI/Anthropic/OpenRouter APIs directly — use @Agent or defineAgentEndpoint
|
|
129
143
|
- NEVER reimplement tool calling loop — the SDK handles it
|
|
144
|
+
- NEVER reimplement file/search/shell tools — use `@theokit/sdk-tools` (readFile, writeFile, search, etc.)
|
|
130
145
|
- NEVER store conversations manually — use @Memory (decorator) or SDK persistence
|
|
131
146
|
- NEVER infer tool capability from method name — always provide explicit `name` + `description`
|
|
132
147
|
- NEVER mix both surfaces for the same endpoint — pick manual OR decorator
|