@theokit/cli 3.0.2 → 4.0.0

package/package.json

@@ -1,18 +1,23 @@
 {
   "name": "@theokit/cli",
-  "version": "3.0.2",
+  "version": "4.0.0",
   "description": "Developer CLI for @theokit/sdk — init, dev, inspect, eval. Adoption Roadmap #1.",
   "license": "Apache-2.0",
+  "homepage": "https://github.com/usetheokit/theokit-sdk#readme",
+  "bugs": "https://github.com/usetheokit/theokit-sdk/issues",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/usetheokit/theokit-sdk.git",
+    "directory": "packages/cli"
+  },
   "type": "module",
+  "sideEffects": false,
   "engines": {
     "node": ">=22.12.0"
   },
   "main": "./dist/index.cjs",
   "module": "./dist/index.js",
   "types": "./dist/index.d.ts",
-  "bin": {
-    "theokit": "./dist/bin/theokit.js"
-  },
   "exports": {
     ".": {
       "import": {
@@ -32,16 +37,20 @@
     "LICENSE",
     "CHANGELOG.md"
   ],
+  "publishConfig": {
+    "provenance": true,
+    "access": "public"
+  },
   "dependencies": {
     "@clack/prompts": "^0.7.0",
     "commander": "^12.1.0",
     "picocolors": "^1.0.0",
     "tsx": "^4.19.0",
     "zod": "^4.0.0",
-    "@theokit/sdk": "^4.43.0"
+    "@theokit/sdk": "^4.54.0"
   },
   "peerDependencies": {
-    "@theokit/acp": "^3.0.2"
+    "@theokit/acp": "^4.0.0"
   },
   "peerDependenciesMeta": {
     "@theokit/acp": {
@@ -53,18 +62,13 @@
     "tsup": "^8.5.0",
     "typescript": "^5.8.0",
     "vitest": "^4.1.8",
-    "@theokit/acp": "3.0.2"
+    "@theokit/acp": "4.0.0"
   },
-  "publishConfig": {
-    "access": "public"
-  },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/usetheodev/theokit-sdk.git",
-    "directory": "packages/cli"
+  "bin": {
+    "theokit": "./dist/bin/theokit.js"
   },
   "scripts": {
-    "build": "tsup",
+    "build": "tsup && node ../../tools/repair-dts-imports.mjs .",
     "typecheck": "tsc --noEmit",
     "test": "vitest run"
   }

package/templates/chatbot/.env.example

@@ -0,0 +1,14 @@
+# Copy to .env and fill in:
+#
+# THEOKIT_API_KEY — any non-empty string. Used by the SDK for cloud
+# catalog reads; not strictly required for chat against Anthropic/OpenAI
+# directly. Set to "local" if you're not using Theo cloud.
+THEOKIT_API_KEY=local
+
+# Provider key — pick ONE. The SDK auto-detects which one is set.
+# ANTHROPIC_API_KEY=sk-ant-...
+# OPENAI_API_KEY=sk-...
+# OPENROUTER_API_KEY=sk-or-...
+
+# Override the model (default: anthropic/claude-3-5-sonnet-latest).
+# AGENT_MODEL=openai/gpt-4o-mini

package/templates/chatbot/README.md

@@ -0,0 +1,34 @@
+# {{projectName}}
+
+A conversational agent that remembers, scaffolded by `theokit init`.
+
+## Setup
+
+```bash
+pnpm install
+cp .env.example .env
+# Edit .env — set ANTHROPIC_API_KEY / OPENAI_API_KEY / OPENROUTER_API_KEY
+pnpm dev
+```
+
+## What this does
+
+1. `Agent.getOrCreate(id, …)` — a stable id, so a second run resumes the same
+   conversation instead of starting a fresh one.
+2. Reads a line, streams the reply, loops.
+3. Reports `result.status === "error"` with the provider's reason, so a run that
+   ends without answering says why.
+
+Persistence needs no configuration: every finished turn is appended to a session
+transcript automatically. `SESSION_DIR` only chooses where it lands.
+
+## Requirements
+
+- Node 22.12+.
+- One of: Anthropic / OpenAI / OpenRouter API key.
+
+## Next steps
+
+- `SESSION_DIR=~/.claude` writes sessions the Claude Code CLI can `--continue`.
+- `AGENT_ID=support` runs a second, independent conversation from the same code.
+- Add tools with `Tool.create({ name, description, inputSchema, handler })`.

package/templates/chatbot/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "{{projectName}}",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "tsx --env-file=.env src/index.ts",
+    "start": "tsx --env-file=.env src/index.ts"
+  },
+  "dependencies": {
+    "@theokit/sdk": "^{{sdkVersion}}"
+  },
+  "devDependencies": {
+    "tsx": "^4.19.0",
+    "typescript": "^5.8.0"
+  },
+  "engines": {
+    "node": ">=22.12.0"
+  }
+}

package/templates/chatbot/src/index.ts

@@ -0,0 +1,88 @@
+/**
+ * {{projectName}} — a conversational agent that remembers.
+ *
+ * Reads a line, streams the reply, and keeps the thread going. Every finished
+ * turn is persisted automatically, so the conversation survives a restart —
+ * there is nothing to wire for that. `local.sessionDir` only chooses WHERE the
+ * transcript lives; point it at `~/.claude` and the Claude Code CLI can
+ * `--continue` the same session.
+ */
+
+import { createInterface } from "node:readline/promises";
+import { Agent, type Run } from "@theokit/sdk";
+
+const API_KEY = process.env.THEOKIT_API_KEY ?? "local";
+const MODEL = process.env.AGENT_MODEL ?? "anthropic/claude-3-5-sonnet-latest";
+
+/** A stable id is what makes the next run resume this conversation instead of starting a new one. */
+const AGENT_ID = process.env.AGENT_ID ?? "chatbot";
+
+/**
+ * Drain one run's assistant stream to stdout and hand back the text.
+ *
+ * Extracted because the loop is the same in every template and nests three deep inside whatever
+ * calls it — reading it once here beats re-reading it inside each caller.
+ */
+async function streamReply(run: Run): Promise<string> {
+  let text = "";
+  for await (const event of run.stream()) {
+    if (event.type !== "assistant") continue;
+    for (const part of event.message.content) {
+      if (part.type === "text") {
+        process.stdout.write(part.text);
+        text += part.text;
+      }
+    }
+  }
+  return text;
+}
+
+async function main(): Promise<void> {
+  // `getOrCreate` — not `create`. On a second run it reattaches to the stored
+  // transcript for this id; `create` would start a fresh thread each time.
+  const agent = await Agent.getOrCreate(AGENT_ID, {
+    apiKey: API_KEY,
+    model: { id: MODEL },
+    local: {
+      cwd: process.cwd(),
+      ...(process.env.SESSION_DIR !== undefined ? { sessionDir: process.env.SESSION_DIR } : {}),
+    },
+    systemPrompt:
+      "You are a friendly assistant. Keep answers to one to three sentences, " +
+      "and use what was said earlier in the conversation.",
+  });
+
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  console.log(`${AGENT_ID} ready · model ${MODEL} · Ctrl+C to quit\n`);
+
+  // A `for await` over the prompt, not a recursive callback: the loop below
+  // reads as the conversation it is, and an error in one turn does not bury the
+  // stack under every turn before it.
+  try {
+    while (true) {
+      const line = (await rl.question("You: ")).trim();
+      if (line.length === 0) continue;
+
+      const run = await agent.send(line);
+      process.stdout.write("Bot: ");
+      await streamReply(run);
+
+      const result = await run.wait();
+      process.stdout.write("\n\n");
+
+      // A run can END without succeeding. Reporting the reason here is the
+      // difference between "the bot went quiet" and a diagnosis.
+      if (result.status === "error") {
+        console.error(`run failed: ${result.error?.message ?? "no reason reported"}\n`);
+      }
+    }
+  } finally {
+    rl.close();
+    await agent.dispose();
+  }
+}
+
+main().catch((cause) => {
+  console.error("chatbot failed:", cause instanceof Error ? cause.message : cause);
+  process.exit(1);
+});

package/templates/chatbot/tsconfig.json

@@ -0,0 +1,12 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "lib": ["ES2023", "ESNext.Disposable"]
+  },
+  "include": ["src/**/*.ts"]
+}

package/templates/minimal/README.md

@@ -24,6 +24,6 @@ pnpm dev
 
 ## Next steps
 
-- Add custom tools via `defineTool` (see `@theokit/sdk` docs).
+- Add custom tools with `Tool.create({ name, description, inputSchema, handler })`.
 - Switch to a local Ollama model by setting `AGENT_MODEL=ollama/llama3.2:3b`.
 - Wire to a chat platform via `@theokit/gateway`.

package/templates/multi-agent/.env.example

@@ -0,0 +1,14 @@
+# Copy to .env and fill in:
+#
+# THEOKIT_API_KEY — any non-empty string. Used by the SDK for cloud
+# catalog reads; not strictly required for chat against Anthropic/OpenAI
+# directly. Set to "local" if you're not using Theo cloud.
+THEOKIT_API_KEY=local
+
+# Provider key — pick ONE. The SDK auto-detects which one is set.
+# ANTHROPIC_API_KEY=sk-ant-...
+# OPENAI_API_KEY=sk-...
+# OPENROUTER_API_KEY=sk-or-...
+
+# Override the model (default: anthropic/claude-3-5-sonnet-latest).
+# AGENT_MODEL=openai/gpt-4o-mini

package/templates/multi-agent/README.md

@@ -0,0 +1,33 @@
+# {{projectName}}
+
+A router and two specialists, scaffolded by `theokit init`.
+
+## Setup
+
+```bash
+pnpm install
+cp .env.example .env
+pnpm dev "Translate to French: good morning"
+```
+
+## What this does
+
+1. `AgentFactory.create({ … })` captures the configuration all three agents
+   share — key, model, workspace.
+2. A classifier reads the input and names the specialist.
+3. `factory.forSession(id, { systemPrompt })` builds that specialist; only the
+   prompt differs.
+
+Writing `Agent.create` three times would work, and would drift the shared half
+apart on the first edit. The factory is what keeps one prefix in one place.
+
+## Requirements
+
+- Node 22.12+.
+- One of: Anthropic / OpenAI / OpenRouter API key.
+
+## Next steps
+
+- Swap `forSession` for `getOrCreate` when a specialist should remember earlier
+  turns.
+- Add a specialist by adding one entry to `SPECIALISTS` — nothing else changes.

package/templates/multi-agent/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "{{projectName}}",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "tsx --env-file=.env src/index.ts",
+    "start": "tsx --env-file=.env src/index.ts"
+  },
+  "dependencies": {
+    "@theokit/sdk": "^{{sdkVersion}}"
+  },
+  "devDependencies": {
+    "tsx": "^4.19.0",
+    "typescript": "^5.8.0"
+  },
+  "engines": {
+    "node": ">=22.12.0"
+  }
+}

package/templates/multi-agent/src/index.ts

@@ -0,0 +1,90 @@
+/**
+ * {{projectName}} — a router and two specialists.
+ *
+ * A classifier reads the input and names the specialist; that specialist answers.
+ * All three share one configuration prefix through `AgentFactory`, so the only
+ * thing that varies per agent is its system prompt.
+ */
+
+import { AgentFactory, type Run } from "@theokit/sdk";
+
+const API_KEY = process.env.THEOKIT_API_KEY ?? "local";
+const MODEL = process.env.AGENT_MODEL ?? "anthropic/claude-3-5-sonnet-latest";
+
+/** The whole difference between the three agents. */
+const SPECIALISTS = {
+  classifier:
+    'Reply with exactly one word and nothing else: "summarize" if the user wants a ' +
+    'summary, "translate" if they want a translation, otherwise "summarize".',
+  summarizer: "Condense the input into two or three bullet points. No preamble.",
+  translator:
+    "Translate the input to the language the user names. If none is named, " +
+    "translate to English. Reply with the translation only.",
+} as const;
+
+type Specialist = keyof typeof SPECIALISTS;
+
+// One prefix, many agents — this is what `AgentFactory` is for. Writing
+// `Agent.create` three times would drift the shared half apart on the first edit.
+const factory = AgentFactory.create({
+  apiKey: API_KEY,
+  model: { id: MODEL },
+  local: { cwd: process.cwd() },
+});
+
+/**
+ * Drain one run's assistant stream and hand back the text.
+ *
+ * Extracted because the loop is the same in every template and nests three deep inside whatever
+ * calls it — reading it once here beats re-reading it inside each caller.
+ */
+async function streamReply(run: Run): Promise<string> {
+  let text = "";
+  for await (const event of run.stream()) {
+    if (event.type !== "assistant") continue;
+    for (const part of event.message.content) {
+      if (part.type === "text") {
+        text += part.text;
+      }
+    }
+  }
+  return text;
+}
+
+async function ask(role: Specialist, message: string): Promise<string> {
+  // `forSession` — a fresh agent per call. Use `getOrCreate` instead when the
+  // specialist should remember earlier turns.
+  const agent = await factory.forSession(`multi-${role}`, {
+    systemPrompt: SPECIALISTS[role],
+  });
+  try {
+    const run = await agent.send(message);
+    const reply = await streamReply(run);
+    const result = await run.wait();
+    if (result.status === "error") {
+      throw new Error(`${role} failed: ${result.error?.message ?? "no reason reported"}`);
+    }
+    return reply.trim();
+  } finally {
+    await agent.dispose();
+  }
+}
+
+async function main(): Promise<void> {
+  const input = process.argv[2] ?? "Summarize: the quick brown fox jumps over the lazy dog.";
+  console.log(`Input: ${input}\n`);
+
+  const verdict = (await ask("classifier", input)).toLowerCase();
+  // The model is asked for one word and usually gives one. `includes` rather
+  // than `===` so a stray period or quote does not silently route everything
+  // to the fallback — the failure would look like a bad classifier.
+  const role: Specialist = verdict.includes("translate") ? "translator" : "summarizer";
+  console.log(`Router chose: ${role} (said "${verdict}")\n`);
+
+  console.log(await ask(role, input));
+}
+
+main().catch((cause) => {
+  console.error("multi-agent failed:", cause instanceof Error ? cause.message : cause);
+  process.exit(1);
+});

package/templates/multi-agent/tsconfig.json

@@ -0,0 +1,12 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "lib": ["ES2023", "ESNext.Disposable"]
+  },
+  "include": ["src/**/*.ts"]
+}

package/templates/rag-agent/.env.example

@@ -0,0 +1,14 @@
+# Copy to .env and fill in:
+#
+# THEOKIT_API_KEY — any non-empty string. Used by the SDK for cloud
+# catalog reads; not strictly required for chat against Anthropic/OpenAI
+# directly. Set to "local" if you're not using Theo cloud.
+THEOKIT_API_KEY=local
+
+# Provider key — pick ONE. The SDK auto-detects which one is set.
+# ANTHROPIC_API_KEY=sk-ant-...
+# OPENAI_API_KEY=sk-...
+# OPENROUTER_API_KEY=sk-or-...
+
+# Override the model (default: anthropic/claude-3-5-sonnet-latest).
+# AGENT_MODEL=openai/gpt-4o-mini

package/templates/rag-agent/README.md

@@ -0,0 +1,34 @@
+# {{projectName}}
+
+Retrieval-augmented generation over your own files, scaffolded by `theokit init`.
+
+## Setup
+
+```bash
+pnpm install
+cp .env.example .env
+mkdir -p .theokit/memory && echo "# Notes" > .theokit/memory/MEMORY.md
+pnpm dev "What is in this knowledge base?"
+```
+
+## What this does
+
+1. `Memory.openIndex({ cwd })` — SQLite full-text search, no native dependency.
+2. `index.sync()` scans `.theokit/memory/` and reports what it indexed. An empty
+   index says so up front, so a thin answer is not mistaken for a weak model.
+3. `Tool.create(…)` exposes the index to the model, which decides when to search.
+4. The agent answers from retrieved snippets and cites them.
+
+`sources` belongs to the SEARCH, not to opening the index — it narrows which
+corpora a single query reads.
+
+## Requirements
+
+- Node 22.12+.
+- One of: Anthropic / OpenAI / OpenRouter API key.
+
+## Next steps
+
+- Hybrid vector recall: `Memory.openIndex({ cwd, embedding: { provider: "openai" } })`.
+- LanceDB backend: `backend: "lance"` — which then REQUIRES an embedding runtime
+  and the `@lancedb/lancedb` peer.

package/templates/rag-agent/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "{{projectName}}",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "tsx --env-file=.env src/index.ts",
+    "start": "tsx --env-file=.env src/index.ts"
+  },
+  "dependencies": {
+    "@theokit/sdk": "^{{sdkVersion}}",
+    "zod": "^4.0.0"
+  },
+  "devDependencies": {
+    "tsx": "^4.19.0",
+    "typescript": "^5.8.0"
+  },
+  "engines": {
+    "node": ">=22.12.0"
+  }
+}

package/templates/rag-agent/src/index.ts

@@ -0,0 +1,115 @@
+/**
+ * {{projectName}} — retrieval-augmented generation over your own files.
+ *
+ * Indexes `.theokit/memory/`, exposes the index to the model as a tool, and
+ * lets the model decide when to search. The agent answers from retrieved
+ * snippets and cites them.
+ */
+
+import { Agent, Memory, type Run, Tool } from "@theokit/sdk";
+import { z } from "zod";
+
+const API_KEY = process.env.THEOKIT_API_KEY ?? "local";
+const MODEL = process.env.AGENT_MODEL ?? "anthropic/claude-3-5-sonnet-latest";
+
+/**
+ * Drain one run's assistant stream to stdout and hand back the text.
+ *
+ * Extracted because the loop is the same in every template and nests three deep inside whatever
+ * calls it — reading it once here beats re-reading it inside each caller.
+ */
+async function streamReply(run: Run): Promise<string> {
+  let text = "";
+  for await (const event of run.stream()) {
+    if (event.type !== "assistant") continue;
+    for (const part of event.message.content) {
+      if (part.type === "text") {
+        process.stdout.write(part.text);
+        text += part.text;
+      }
+    }
+  }
+  return text;
+}
+
+async function main(): Promise<void> {
+  // Default backend is SQLite with full-text search and no native dependency.
+  // Add `embedding: { provider: "openai" }` for hybrid vector recall, or
+  // `backend: "lance"` (which then REQUIRES an embedding runtime).
+  const index = await Memory.openIndex({ cwd: process.cwd() });
+
+  try {
+    const synced = await index.sync();
+    console.log(
+      `Indexed ${synced.filesScanned} file(s) · ${synced.chunksWritten} chunk(s) written · ` +
+        `backend ${index.status().backend}`,
+    );
+
+    if (index.status().chunksIndexed === 0) {
+      // Saying this up front is the difference between "the model is bad" and
+      // "there was nothing to retrieve".
+      console.warn(
+        "\nThe index is empty. Put some markdown under .theokit/memory/ and re-run,\n" +
+          "otherwise the agent has nothing to cite and will say so.\n",
+      );
+    }
+
+    const searchKnowledge = Tool.create({
+      name: "search_knowledge",
+      description:
+        "Search the local knowledge base and return matching snippets with citations. " +
+        "Call this before answering any question about the user's own documents.",
+      inputSchema: z.object({
+        query: z.string().describe("What to look for, in natural language."),
+        maxResults: z.number().int().min(1).max(20).default(5),
+      }),
+      handler: async ({ query, maxResults }) => {
+        // `sources` belongs to the SEARCH, not to opening the index: it narrows
+        // which corpora this one query reads.
+        const hits = await index.search(query, {
+          maxResults,
+          sources: ["memory", "wiki"],
+        });
+        if (hits.length === 0) return "No matching documents.";
+        return hits
+          .map((h, i) => `[${i + 1}] ${h.citation} (score ${h.score.toFixed(2)})\n${h.snippet}`)
+          .join("\n\n");
+      },
+    });
+
+    const agent = await Agent.create({
+      agentId: "rag-agent",
+      apiKey: API_KEY,
+      model: { id: MODEL },
+      systemPrompt:
+        "Answer from the local knowledge base. Call search_knowledge first, cite the " +
+        "sources it returns by their [n] markers, and say plainly when the base does " +
+        "not contain the answer rather than filling the gap from memory.",
+      tools: [searchKnowledge],
+      local: { cwd: process.cwd() },
+    });
+
+    try {
+      const question = process.argv[2] ?? "What is in this knowledge base?";
+      console.log(`\nQuestion: ${question}\n`);
+
+      const run = await agent.send(question);
+      await streamReply(run);
+      const result = await run.wait();
+      process.stdout.write("\n");
+      if (result.status === "error") {
+        console.error(`\nrun failed: ${result.error?.message ?? "no reason reported"}`);
+        process.exitCode = 1;
+      }
+    } finally {
+      await agent.dispose();
+    }
+  } finally {
+    await index.close();
+  }
+}
+
+main().catch((cause) => {
+  console.error("rag-agent failed:", cause instanceof Error ? cause.message : cause);
+  process.exit(1);
+});

package/templates/rag-agent/tsconfig.json

@@ -0,0 +1,12 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "lib": ["ES2023", "ESNext.Disposable"]
+  },
+  "include": ["src/**/*.ts"]
+}

package/templates/telegram-bot/README.md

@@ -22,14 +22,14 @@ Then DM your bot in Telegram. Every message gets streamed through the agent.
 ## What this does
 
 - `GatewayRunner` + `TelegramAdapter` handle the platform plumbing.
-- `createAgentFactory` keeps one persistent agent per chat (memory + state
-  preserved across turns).
+- `AgentFactory.create` captures the shared config once; `factory.getOrCreate`
+  keeps one persistent agent per chat, so memory and state survive across turns.
 - Each inbound message → `agent.send` → reply back via `ctx.reply`.
 
 ## Customize
 
 - Switch model: `AGENT_MODEL=ollama/llama3.2:3b` for local Ollama.
-- Add custom tools: import `defineTool` from `@theokit/sdk` and pass via
-  `createAgentFactory({ tools: [...] })`.
+- Add custom tools: `Tool.create({ name, description, inputSchema, handler })`
+  from `@theokit/sdk`, passed as `AgentFactory.create({ tools: [...] })`.
 - Slash commands: `runner.command("name", handler)` — see
   `@theokit/gateway` docs.

package/templates/telegram-bot/package.json

@@ -9,8 +9,8 @@
   },
   "dependencies": {
     "@theokit/sdk": "^{{sdkVersion}}",
-    "@theokit/gateway": "^{{sdkVersion}}",
-    "@theokit/gateway-telegram": "^{{sdkVersion}}",
+    "@theokit/gateway": "^0.5.0",
+    "@theokit/gateway-telegram": "^0.1.0",
     "grammy": "^1.30.0",
     "zod": "^4.0.0"
   },