@theokit/cli 0.1.1

package/templates/ollama-local/src/index.ts

@@ -0,0 +1,51 @@
+/**
+ * {{projectName}} — 100% local agent via Ollama (ADR D182).
+ *
+ * Zero remote API keys required. Boots Ollama (must be running locally),
+ * pre-warms the model, sends a prompt, streams the reply.
+ */
+
+import { Agent } from "@theokit/sdk";
+
+const OLLAMA_HOST = process.env.OLLAMA_HOST ?? "http://localhost:11434";
+const MODEL = process.env.OLLAMA_MODEL ?? "ollama/llama3.2:3b";
+
+async function streamAssistantText(
+  run: Awaited<ReturnType<Awaited<ReturnType<typeof Agent.create>>["send"]>>,
+): Promise<void> {
+  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);
+    }
+  }
+}
+
+async function main(): Promise<void> {
+  const agent = await Agent.create({
+    apiKey: process.env.THEOKIT_API_KEY ?? "local",
+    model: { id: MODEL },
+    local: { cwd: process.cwd() },
+    systemPrompt:
+      "You are a concise assistant. Respond in one or two short sentences. No greetings.",
+  });
+
+  console.log(`Agent: ${agent.agentId}`);
+  console.log(`Model: ${MODEL}`);
+  console.log(`Host:  ${OLLAMA_HOST}\n`);
+
+  const run = await agent.send("Explain what dependency injection is, in one sentence.");
+  await streamAssistantText(run);
+  await run.wait();
+  process.stdout.write("\n");
+}
+
+main().catch((cause) => {
+  const message = cause instanceof Error ? cause.message : String(cause);
+  console.error("ollama agent failed:", message);
+  if (/ollama_unreachable|ECONNREFUSED/.test(message)) {
+    console.error("\nHint: run `ollama serve` to start the local runtime,");
+    console.error("or set OLLAMA_HOST to point at a remote Ollama box.");
+  }
+  process.exit(1);
+});

package/templates/ollama-local/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/.env.example

@@ -0,0 +1,15 @@
+# Telegram bot token from @BotFather (https://t.me/BotFather)
+# 1. /start → /newbot → follow prompts → copy the token here.
+TELEGRAM_BOT_TOKEN=
+
+# Provider key — pick ONE.
+# ANTHROPIC_API_KEY=sk-ant-...
+# OPENAI_API_KEY=sk-...
+# OPENROUTER_API_KEY=sk-or-...
+
+# THEOKIT_API_KEY — any non-empty string. Default: "local".
+THEOKIT_API_KEY=local
+
+# AGENT_MODEL — override the default (anthropic/claude-3-5-sonnet-latest).
+# For local Ollama:
+# AGENT_MODEL=ollama/llama3.2:3b

package/templates/telegram-bot/README.md

@@ -0,0 +1,35 @@
+# {{projectName}}
+
+A Telegram bot powered by `@theokit/sdk` + `@theokit/gateway` — scaffolded
+by `theokit init --template telegram-bot`.
+
+## Setup
+
+```bash
+# 1. Create a bot via @BotFather: https://t.me/BotFather
+#    /start → /newbot → name it → copy the token.
+# 2. Configure:
+cp .env.example .env
+# Edit .env: set TELEGRAM_BOT_TOKEN and ONE of the provider API keys.
+
+# 3. Install + run:
+pnpm install
+pnpm dev
+```
+
+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).
+- 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: [...] })`.
+- Slash commands: `runner.command("name", handler)` — see
+  `@theokit/gateway` docs.

package/templates/telegram-bot/package.json

@@ -0,0 +1,24 @@
+{
+  "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}}",
+    "@theokit/gateway": "^{{sdkVersion}}",
+    "@theokit/gateway-telegram": "^{{sdkVersion}}",
+    "grammy": "^1.30.0",
+    "zod": "^3.25.0"
+  },
+  "devDependencies": {
+    "tsx": "^4.19.0",
+    "typescript": "^5.8.0"
+  },
+  "engines": {
+    "node": ">=22.12.0"
+  }
+}

package/templates/telegram-bot/src/index.ts

@@ -0,0 +1,66 @@
+/**
+ * {{projectName}} — a Telegram bot powered by @theokit/sdk + @theokit/gateway.
+ *
+ * Boots a grammy bot, routes every inbound message through Agent.send,
+ * streams the reply back to Telegram.
+ */
+
+import { GatewayRunner } from "@theokit/gateway";
+import { TelegramAdapter } from "@theokit/gateway-telegram";
+import { createAgentFactory } from "@theokit/sdk";
+import { Bot } from "grammy";
+
+const TELEGRAM_BOT_TOKEN = process.env.TELEGRAM_BOT_TOKEN;
+if (TELEGRAM_BOT_TOKEN === undefined || TELEGRAM_BOT_TOKEN.length === 0) {
+  console.error(
+    "ABORT: TELEGRAM_BOT_TOKEN missing. Create a bot via @BotFather and add it to .env.",
+  );
+  process.exit(1);
+}
+
+const API_KEY = process.env.THEOKIT_API_KEY ?? "local";
+const MODEL = process.env.AGENT_MODEL ?? "anthropic/claude-3-5-sonnet-latest";
+
+const factory = createAgentFactory({
+  apiKey: API_KEY,
+  model: { id: MODEL },
+  local: { cwd: process.cwd() },
+  systemPrompt: "You are a concise Telegram assistant. Reply in one or two sentences.",
+});
+
+const bot = new Bot(TELEGRAM_BOT_TOKEN);
+const adapter = new TelegramAdapter({ bot });
+
+async function collectReply(
+  run: Awaited<ReturnType<Awaited<ReturnType<typeof factory.getOrCreate>>["send"]>>,
+): Promise<string> {
+  let reply = "";
+  for await (const e of run.stream()) {
+    if (e.type !== "assistant") continue;
+    for (const part of e.message.content) {
+      if (part.type === "text") reply += part.text;
+    }
+  }
+  await run.wait();
+  return reply;
+}
+
+const runner = new GatewayRunner({
+  adapters: [adapter],
+  handler: async (event, ctx) => {
+    if (event.text.length === 0) return;
+    const agentId = `${event.platform}-dm-${event.sender.id}`;
+    const agent = await factory.getOrCreate(agentId);
+    const run = await agent.send(event.text);
+    const reply = await collectReply(run);
+    if (reply.length > 0) await ctx.reply(reply);
+  },
+});
+
+await runner.start();
+console.log(`Bot started. Send a message in Telegram to your bot.`);
+
+process.on("SIGINT", async () => {
+  await runner.stop();
+  process.exit(0);
+});

package/templates/telegram-bot/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"]
+}