create-bk-agent 0.17.0 → 0.17.2

package/dist/src/add/modules/server.js

@@ -85,7 +85,7 @@ function addServer(info, args) {
     }
     fs.writeFileSync(info.serverFile, generateServerTs(info, opts));
     console.log(`\n✓  Created src/server.ts  (HTTP MCP on port ${opts.port})`);
-    const added = (0, patcher_1.addPackageDependency)(info.pkgFile, '@backendkit-labs/mcp-server', '^0.16.0');
+    const added = (0, patcher_1.addPackageDependency)(info.pkgFile, '@backendkit-labs/mcp-server', '^0.15.0');
     (0, patcher_1.addPackageDependency)(info.pkgFile, 'zod', '^3.25.0');
     (0, patcher_1.addPackageScript)(info.pkgFile, 'server', 'ts-node src/server.ts');
     if (added) {

package/dist/src/scaffold.js

@@ -83,6 +83,7 @@ const DEPLOY_SCRIPTS = {
         delete s['start'];
     },
 };
+const MCP_DEPLOY_MODES = ['mcp-http', 'mcp-stdio', 'hybrid'];
 function patchPackageJson(dir, projectName, deployMode) {
     const pkgPath = path.join(dir, 'package.json');
     if (!fs.existsSync(pkgPath))
@@ -93,6 +94,10 @@ function patchPackageJson(dir, projectName, deployMode) {
         pkg.scripts ??= {};
         DEPLOY_SCRIPTS[deployMode](pkg.scripts);
     }
+    if (deployMode && MCP_DEPLOY_MODES.includes(deployMode)) {
+        pkg.dependencies ??= {};
+        pkg.dependencies['@backendkit-labs/mcp-server'] ??= '^0.15.0';
+    }
     fs.writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + '\n');
 }
 // ── Write .env stub ───────────────────────────────────────────────────────────

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-bk-agent",
-  "version": "0.17.0",
+  "version": "0.17.2",
   "description": "Create a new BackendKit agent project",
   "main": "dist/src/index.js",
   "bin": {

package/templates/base/autonomous/.env.example

@@ -0,0 +1,4 @@
+ANTHROPIC_API_KEY=sk-ant-...
+# or: OPENAI_API_KEY=sk-...
+LLM_PROVIDER=anthropic
+WEBHOOK_PORT=3000

package/templates/base/autonomous/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "my-autonomous-agent",
+  "version": "0.1.0",
+  "private": true,
+  "description": "Autonomous agent — activates on cron, webhooks, or custom events",
+  "main": "dist/index.js",
+  "scripts": {
+    "dev": "ts-node src/index.ts",
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@backendkit-labs/agent-core": "^0.16.0",
+    "dotenv": "^16.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "ts-node": "^10.9.0",
+    "typescript": "^5.4.0"
+  },
+  "engines": { "node": ">=20.0.0" }
+}

package/templates/base/autonomous/src/index.ts

@@ -0,0 +1,83 @@
+import 'dotenv/config';
+import * as os from 'os';
+import * as path from 'path';
+import { createAutonomousAgent, createMemorySystem } from '@backendkit-labs/agent-core';
+import type { AgentProfile } from '@backendkit-labs/agent-core';
+
+// ── Agent definition ──────────────────────────────────────────────────────────
+
+const monitorAgent: AgentProfile = {
+    id: 'monitor',
+    name: 'Monitor',
+    icon: '👁',
+    description: 'Monitors events and executes scheduled tasks',
+    allowedTools: [],
+    delegatesTo: [],
+    systemPrompt: `You are an autonomous monitor agent.
+// TODO: describe what this agent monitors and what actions it takes.
+When activated by a trigger, analyze the input and take appropriate action.`,
+};
+
+// ── Provider ──────────────────────────────────────────────────────────────────
+
+const provider = process.env.LLM_PROVIDER ?? 'anthropic';
+const apiKey   = process.env.ANTHROPIC_API_KEY ?? process.env.OPENAI_API_KEY ?? '';
+
+if (!apiKey) { console.error('Missing API key'); process.exit(1); }
+
+// ── Memory — persists context between trigger executions ──────────────────────
+
+const APP_DIR = path.join(os.homedir(), '.my-autonomous-agent');
+const MEM_DIR = path.join(APP_DIR, 'memory');
+
+const memory = createMemorySystem({
+    episodic:   { provider: 'json', path: path.join(MEM_DIR, 'episodes.json') },
+    semantic:   { provider: 'json', path: path.join(MEM_DIR, 'knowledge.json') },
+    procedural: { provider: 'json', path: path.join(MEM_DIR, 'patterns.json') },
+    retention:  { maxEpisodes: 200 },
+});
+
+// ── Autonomous agent ──────────────────────────────────────────────────────────
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+const agent = createAutonomousAgent({
+    providers:       { [provider]: { apiKey } } as any,
+    defaultProvider: provider,
+    agents:          [monitorAgent],
+    defaultAgent:    'monitor',
+    goal:            'TODO: describe the agent goal',
+    memorySystem:    memory,
+
+    triggers: [
+        // Run every day at 9:00 AM
+        {
+            type: 'schedule',
+            cron: '0 9 * * *',
+            task: 'Run daily check and report findings',
+        },
+
+        // Listen for webhook events (e.g. from GitHub, Slack, etc.)
+        {
+            type:   'webhook',
+            path:   '/events',
+            // secret: process.env.WEBHOOK_SECRET,
+        },
+
+        // TODO: add more triggers as needed
+        // { type: 'event', topic: 'my.custom.event' },
+    ],
+
+    webhookPort: parseInt(process.env.WEBHOOK_PORT ?? '3000'),
+});
+
+// ── Start ─────────────────────────────────────────────────────────────────────
+
+void (async () => {
+    await agent.start();
+    console.log('Autonomous agent started.');
+    console.log('Webhook listening on port', process.env.WEBHOOK_PORT ?? 3000);
+    console.log(`Memory stored in: ${APP_DIR}`);
+
+    process.on('SIGTERM', async () => { await agent.stop(); process.exit(0); });
+    process.on('SIGINT',  async () => { await agent.stop(); process.exit(0); });
+})();

package/templates/base/autonomous/tsconfig.json

@@ -0,0 +1,17 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "commonjs",
+    "moduleResolution": "node",
+    "lib": ["ES2022"],
+    "types": ["node"],
+    "outDir": "dist",
+    "rootDir": "src",
+    "strict": true,
+    "skipLibCheck": true,
+    "esModuleInterop": true,
+    "resolveJsonModule": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}

package/templates/base/coding/.env.example

@@ -0,0 +1,4 @@
+ANTHROPIC_API_KEY=sk-ant-...
+# or: OPENAI_API_KEY=sk-...
+LLM_PROVIDER=anthropic
+LLM_MODEL=claude-sonnet-4-6

package/templates/base/coding/AGENT.md

@@ -0,0 +1,13 @@
+# My Coding Agent
+
+TODO: Describe your project here. The agent reads this file to understand the codebase.
+
+## Tech stack
+- TODO: list your languages, frameworks, and tools
+
+## Key directories
+- `src/` — main source code
+- `tests/` — test files
+
+## Coding conventions
+- TODO: describe naming conventions, patterns, and rules to follow

package/templates/base/coding/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "my-coding-agent",
+  "version": "0.1.0",
+  "private": true,
+  "description": "Coding assistant agent — edit files, run commands, search code",
+  "main": "dist/index.js",
+  "scripts": {
+    "dev": "ts-node src/index.ts",
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@backendkit-labs/agent-coding": "^0.16.0",
+    "@backendkit-labs/agent-core": "^0.16.0",
+    "dotenv": "^16.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "ts-node": "^10.9.0",
+    "typescript": "^5.4.0"
+  },
+  "engines": { "node": ">=20.0.0" }
+}

package/templates/base/coding/src/index.ts

@@ -0,0 +1,42 @@
+import 'dotenv/config';
+import * as readline from 'readline';
+import { createCodingEngine, TerminalTransport } from '@backendkit-labs/agent-coding';
+
+// ── Provider setup ────────────────────────────────────────────────────────────
+
+const provider = process.env.LLM_PROVIDER ?? 'anthropic';
+const apiKey   = process.env.ANTHROPIC_API_KEY ?? process.env.OPENAI_API_KEY ?? process.env.LLM_API_KEY ?? '';
+const model    = process.env.LLM_MODEL;
+
+if (!apiKey) {
+    console.error('Missing API key. Set ANTHROPIC_API_KEY or OPENAI_API_KEY in .env');
+    process.exit(1);
+}
+
+// ── Engine ────────────────────────────────────────────────────────────────────
+
+const transport = new TerminalTransport();
+
+const engine = createCodingEngine({
+    providers:       { [provider]: { apiKey, ...(model ? { model } : {}) } },
+    defaultProvider: provider,
+    workingDir:      process.cwd(),
+    appName:         'my-coding-agent',
+    transport,
+});
+
+// ── REPL ──────────────────────────────────────────────────────────────────────
+
+const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+
+function prompt() {
+    rl.question('\n❯ ', async (input) => {
+        const trimmed = input.trim();
+        if (!trimmed || trimmed === '/exit') { rl.close(); return; }
+        await engine.run(trimmed);
+        prompt();
+    });
+}
+
+console.log('Coding agent ready. Type your request or /exit to quit.\n');
+prompt();

package/templates/base/coding/tsconfig.json

@@ -0,0 +1,17 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "commonjs",
+    "moduleResolution": "node",
+    "lib": ["ES2022"],
+    "types": ["node"],
+    "outDir": "dist",
+    "rootDir": "src",
+    "strict": true,
+    "skipLibCheck": true,
+    "esModuleInterop": true,
+    "resolveJsonModule": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}

package/templates/base/minimal/.env.example

@@ -0,0 +1 @@
+ANTHROPIC_API_KEY=sk-ant-...

package/templates/base/minimal/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "my-agent",
+  "version": "0.1.0",
+  "private": true,
+  "description": "Minimal agent — full control over engine configuration",
+  "main": "dist/index.js",
+  "scripts": {
+    "dev": "ts-node src/index.ts",
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@backendkit-labs/agent-core": "^0.16.0",
+    "dotenv": "^16.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "ts-node": "^10.9.0",
+    "typescript": "^5.4.0"
+  },
+  "engines": { "node": ">=20.0.0" }
+}

package/templates/base/minimal/src/index.ts

@@ -0,0 +1,43 @@
+import 'dotenv/config';
+import { createBaseEngine } from '@backendkit-labs/agent-core';
+import type { AgentProfile, LLMProvider } from '@backendkit-labs/agent-core';
+
+// ── Provider ──────────────────────────────────────────────────────────────────
+// TODO: replace with the actual provider for your chosen LLM
+// e.g. AnthropicProvider from @backendkit-labs/agent-coding
+// or implement LLMProvider interface directly
+
+const myProvider: LLMProvider = {
+    chat: async (_messages, _tools, callbacks) => {
+        // TODO: call your LLM API here
+        callbacks.onDone({ role: 'assistant', content: 'Hello from my agent!' });
+    },
+};
+
+// ── Agent ─────────────────────────────────────────────────────────────────────
+
+const myAgent: AgentProfile = {
+    id: 'my-agent',
+    name: 'My Agent',
+    icon: '🤖',
+    description: 'TODO: describe your agent',
+    allowedTools: [],
+    delegatesTo: [],
+    systemPrompt: 'TODO: write your system prompt here.',
+};
+
+// ── Engine ────────────────────────────────────────────────────────────────────
+
+const engine = createBaseEngine({
+    providers:       { default: myProvider },
+    defaultProvider: 'default',
+    agents:          [myAgent],
+    defaultAgent:    'my-agent',
+});
+
+// ── Run ───────────────────────────────────────────────────────────────────────
+
+void (async () => {
+    const input = process.argv[2] ?? 'Hello';
+    await engine.run(input);
+})();

package/templates/base/minimal/tsconfig.json

@@ -0,0 +1,17 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "commonjs",
+    "moduleResolution": "node",
+    "lib": ["ES2022"],
+    "types": ["node"],
+    "outDir": "dist",
+    "rootDir": "src",
+    "strict": true,
+    "skipLibCheck": true,
+    "esModuleInterop": true,
+    "resolveJsonModule": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}

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

@@ -0,0 +1,7 @@
+# LLM — any OpenAI-compatible endpoint
+LLM_API_KEY=sk-...
+LLM_BASE_URL=https://api.openai.com/v1
+LLM_MODEL=gpt-4o
+
+# TODO: Add your domain-specific env vars here
+# MY_SERVICE_URL=http://localhost:8080

package/templates/base/multi-agent/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "my-agent",
+  "version": "0.1.0",
+  "private": true,
+  "description": "Multi-agent system: orchestrator + domain specialists",
+  "main": "dist/index.js",
+  "scripts": {
+    "dev": "ts-node src/index.ts",
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "server": "ts-node src/server.ts",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@backendkit-labs/agent-core": "^0.16.0",
+    "dotenv": "^16.0.0",
+    "openai": "^4.0.0",
+    "zod": "^3.25.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "ts-node": "^10.9.0",
+    "typescript": "^5.4.0"
+  },
+  "engines": { "node": ">=20.0.0" }
+}

package/templates/base/multi-agent/src/agents/orchestrator.ts

@@ -0,0 +1,22 @@
+import type { AgentProfile } from '@backendkit-labs/agent-core';
+
+// The orchestrator receives every user request and delegates to the right specialist.
+// It does NOT call tools directly — it uses ask_agent to route work.
+export const ORCHESTRATOR_PROFILE: AgentProfile = {
+    id: 'orchestrator',
+    name: 'Orchestrator',
+    icon: '🎯',
+    description: 'Routes requests to the right specialist agent',
+    delegatesTo: ['specialist-a', 'specialist-b'], // TODO: list your specialists
+    allowedTools: [],
+    systemPrompt: `You are the orchestrator for a TODO: <describe your domain> system.
+
+Your ONLY job is to analyze the user request and delegate to the right specialist via ask_agent.
+Do not attempt to handle requests directly.
+
+Available specialists:
+- specialist-a: TODO describe what this specialist handles
+- specialist-b: TODO describe what this specialist handles
+
+Always delegate. Never answer directly.`,
+};

package/templates/base/multi-agent/src/agents/specialist-a.ts

@@ -0,0 +1,17 @@
+import type { AgentProfile } from '@backendkit-labs/agent-core';
+
+// TODO: Rename this file and agent to match your domain (e.g. docker-agent.ts, k8s-agent.ts)
+export const SPECIALIST_A_PROFILE: AgentProfile = {
+    id: 'specialist-a',
+    name: 'Specialist A',
+    icon: '🔧',
+    description: 'TODO: describe what this specialist does',
+    delegatesTo: [],
+    allowedTools: [
+        'example_action', // TODO: list the tool names this agent can use
+    ],
+    systemPrompt: `You are a specialist in TODO: <your domain area>.
+
+Use the available tools to complete the task delegated to you.
+Be precise and report results clearly.`,
+};

package/templates/base/multi-agent/src/agents/specialist-b.ts

@@ -0,0 +1,16 @@
+import type { AgentProfile } from '@backendkit-labs/agent-core';
+
+// TODO: Rename and customize for your second specialist
+export const SPECIALIST_B_PROFILE: AgentProfile = {
+    id: 'specialist-b',
+    name: 'Specialist B',
+    icon: '📊',
+    description: 'TODO: describe what this specialist does',
+    delegatesTo: [],
+    allowedTools: [
+        'example_query', // TODO: list the tool names this agent can use
+    ],
+    systemPrompt: `You are a specialist in TODO: <your domain area>.
+
+Use the available tools to complete the task delegated to you.`,
+};

package/templates/base/multi-agent/src/config.ts

@@ -0,0 +1,19 @@
+import 'dotenv/config';
+
+export interface Config {
+    llmApiKey: string;
+    llmBaseUrl: string;
+    llmModel: string;
+    // TODO: add your domain-specific config fields
+}
+
+export function loadConfig(): Config {
+    const llmApiKey = process.env.LLM_API_KEY ?? '';
+    if (!llmApiKey) throw new Error('Missing LLM_API_KEY in environment');
+
+    return {
+        llmApiKey,
+        llmBaseUrl: process.env.LLM_BASE_URL ?? 'https://api.openai.com/v1',
+        llmModel:   process.env.LLM_MODEL   ?? 'gpt-4o',
+    };
+}

package/templates/base/multi-agent/src/engine.ts

@@ -0,0 +1,77 @@
+import * as os from 'os';
+import * as path from 'path';
+import {
+    AgentEngine,
+    AgentRegistry,
+    ToolRegistry,
+    ProviderRegistry,
+    CallbackTransport,
+    createMemorySystem,
+} from '@backendkit-labs/agent-core';
+import { OpenAICompatibleProvider } from './providers/openai-compatible';
+import { loadConfig } from './config';
+import { ORCHESTRATOR_PROFILE } from './agents/orchestrator';
+import { SPECIALIST_A_PROFILE } from './agents/specialist-a';
+import { SPECIALIST_B_PROFILE } from './agents/specialist-b';
+import { exampleAction, exampleQuery } from './tools/example-tools';
+
+// ── Persistent storage paths ──────────────────────────────────────────────────
+// All state lives in ~/.my-agent/ so it survives restarts.
+
+const APP_DIR    = path.join(os.homedir(), '.my-agent');
+const HISTORY    = path.join(APP_DIR, 'history.json');
+const MEM_DIR    = path.join(APP_DIR, 'memory');
+
+// ── Memory system ─────────────────────────────────────────────────────────────
+// Three-tier: episodic (past experiences) + semantic (knowledge) + procedural (patterns).
+// buildContextBlock() auto-injects relevant memories into each agent turn.
+
+const memory = createMemorySystem({
+    episodic:   { provider: 'json', path: path.join(MEM_DIR, 'episodes.json') },
+    semantic:   { provider: 'json', path: path.join(MEM_DIR, 'knowledge.json') },
+    procedural: { provider: 'json', path: path.join(MEM_DIR, 'patterns.json') },
+    retention:  { maxEpisodes: 500 },
+});
+
+export function createEngine(transport: CallbackTransport): AgentEngine {
+    const config = loadConfig();
+
+    const tools = new ToolRegistry();
+    tools
+        .register(exampleAction)
+        .register(exampleQuery);
+    // Register memory tools so agents can explicitly save/recall memories
+    for (const t of memory.getTools()) tools.register(t);
+    // TODO: register more tools
+
+    const agents = new AgentRegistry();
+    agents
+        .register(ORCHESTRATOR_PROFILE)
+        .register(SPECIALIST_A_PROFILE)
+        .register(SPECIALIST_B_PROFILE);
+    // TODO: register more specialists
+
+    const providers = new ProviderRegistry();
+    providers.register('default', new OpenAICompatibleProvider({
+        apiKey:  config.llmApiKey,
+        baseUrl: config.llmBaseUrl,
+        model:   config.llmModel,
+    }));
+
+    return new AgentEngine({
+        model:            { provider: 'default', id: config.llmModel },
+        agents,
+        tools,
+        providers,
+        defaultProvider:  'default',
+        defaultAgentId:   'orchestrator',
+        transport,
+        maxIterations:    30,
+        iterationMode:    'auto',
+        // Conversation history — persists between runs
+        historyPath:      HISTORY,
+        maxContextMessages: 100,
+        // Long-term memory — injects relevant context each turn
+        memorySystem:     memory,
+    });
+}

package/templates/base/multi-agent/src/providers/openai-compatible.ts

@@ -0,0 +1,104 @@
+import OpenAI from 'openai';
+import type { LLMProvider, LLMMessage, LLMStreamCallbacks, ToolDefinition } from '@backendkit-labs/agent-core';
+
+export interface OpenAICompatibleProviderOptions {
+    apiKey: string;
+    baseUrl: string;
+    model: string;
+    maxRetries?: number;
+}
+
+function isRetryable(err: unknown): boolean {
+    if (err && typeof err === 'object' && 'status' in err) {
+        const s = (err as { status: number }).status;
+        return s === 429 || s >= 500;
+    }
+    return false;
+}
+
+const sleep = (ms: number) => new Promise<void>(r => setTimeout(r, ms));
+
+export class OpenAICompatibleProvider implements LLMProvider {
+    private readonly client: OpenAI;
+    private readonly model: string;
+    private readonly maxRetries: number;
+
+    constructor(opts: OpenAICompatibleProviderOptions) {
+        this.client     = new OpenAI({ apiKey: opts.apiKey, baseURL: opts.baseUrl, maxRetries: 0 });
+        this.model      = opts.model;
+        this.maxRetries = opts.maxRetries ?? 3;
+    }
+
+    async chat(messages: LLMMessage[], tools: ToolDefinition[], callbacks: LLMStreamCallbacks): Promise<void> {
+        const oaiTools = tools.map(t => ({
+            type: 'function' as const,
+            function: { name: t.name, description: t.description, parameters: t.parameters },
+        })) as OpenAI.Chat.ChatCompletionTool[];
+
+        let attempt = 0;
+        let emitted = false;
+
+        while (attempt < this.maxRetries) {
+            attempt++;
+            try {
+                await this.stream(messages, oaiTools, {
+                    ...callbacks,
+                    onChunk: (d) => { emitted = true; callbacks.onChunk?.(d); },
+                });
+                return;
+            } catch (err) {
+                if (emitted || !isRetryable(err) || attempt >= this.maxRetries) {
+                    callbacks.onError(err instanceof Error ? err : new Error(String(err)));
+                    return;
+                }
+                await sleep(Math.min(1000 * 2 ** attempt, 16_000));
+            }
+        }
+    }
+
+    private async stream(
+        messages: LLMMessage[],
+        oaiTools: OpenAI.Chat.ChatCompletionTool[],
+        callbacks: LLMStreamCallbacks,
+    ): Promise<void> {
+        const stream = await this.client.chat.completions.create({
+            model: this.model,
+            messages: messages as OpenAI.Chat.ChatCompletionMessageParam[],
+            tools:       oaiTools.length ? oaiTools : undefined,
+            tool_choice: oaiTools.length ? 'auto'   : undefined,
+            stream: true,
+            stream_options: { include_usage: true },
+        });
+
+        let content = '';
+        const toolBuffers = new Map<number, { id: string; name: string; args: string }>();
+
+        for await (const chunk of stream) {
+            if (chunk.usage) callbacks.onMetrics?.(chunk.usage.prompt_tokens, chunk.usage.completion_tokens);
+            const delta = chunk.choices[0]?.delta;
+            if (!delta) continue;
+            if (delta.content) { content += delta.content; callbacks.onChunk?.(delta.content); }
+            if (delta.tool_calls) {
+                for (const tc of delta.tool_calls) {
+                    if (!toolBuffers.has(tc.index)) toolBuffers.set(tc.index, { id: '', name: '', args: '' });
+                    const buf = toolBuffers.get(tc.index)!;
+                    if (tc.id) buf.id = tc.id;
+                    if (tc.function?.name)      buf.name += tc.function.name;
+                    if (tc.function?.arguments) buf.args += tc.function.arguments;
+                }
+            }
+        }
+
+        const toolCalls = [...toolBuffers.entries()]
+            .sort(([a], [b]) => a - b)
+            .map(([, b]) => ({ id: b.id, type: 'function' as const, function: { name: b.name, arguments: b.args } }));
+
+        for (const tc of toolCalls) callbacks.onToolCall?.(tc.function.name, tc.function.arguments, tc.id);
+
+        callbacks.onDone({
+            role: 'assistant',
+            content: content || null,
+            tool_calls: toolCalls.length ? toolCalls : undefined,
+        });
+    }
+}

package/templates/base/multi-agent/src/tools/example-tools.ts

@@ -0,0 +1,28 @@
+import { defineTool, z } from '@backendkit-labs/agent-core';
+
+// TODO: Replace these with tools that call your actual domain SDK/API
+
+export const exampleAction = defineTool({
+    name: 'example_action',
+    description: 'TODO: describe what this tool does',
+    input: z.object({
+        target: z.string().describe('Target to act on'),
+        // TODO: add more parameters
+    }),
+    execute: async ({ target }) => {
+        // TODO: implement the actual action
+        return `Action executed on: ${target}`;
+    },
+});
+
+export const exampleQuery = defineTool({
+    name: 'example_query',
+    description: 'TODO: describe what this query returns',
+    input: z.object({
+        filter: z.string().optional().describe('Optional filter'),
+    }),
+    execute: async ({ filter }) => {
+        // TODO: implement the actual query
+        return JSON.stringify({ results: [], filter });
+    },
+});

package/templates/base/multi-agent/tsconfig.json

@@ -0,0 +1,17 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "commonjs",
+    "moduleResolution": "node",
+    "lib": ["ES2022"],
+    "types": ["node"],
+    "outDir": "dist",
+    "rootDir": "src",
+    "strict": true,
+    "skipLibCheck": true,
+    "esModuleInterop": true,
+    "resolveJsonModule": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}

package/templates/base/single/.env.example

@@ -0,0 +1,4 @@
+# LLM — any OpenAI-compatible endpoint
+LLM_API_KEY=sk-...
+LLM_BASE_URL=https://api.openai.com/v1
+LLM_MODEL=gpt-4o

package/templates/base/single/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "my-agent",
+  "version": "0.1.0",
+  "private": true,
+  "description": "Single agent with tool registry",
+  "main": "dist/index.js",
+  "scripts": {
+    "dev": "ts-node src/index.ts",
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "server": "ts-node src/server.ts",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@backendkit-labs/agent-core": "^0.16.0",
+    "dotenv": "^16.0.0",
+    "openai": "^4.0.0",
+    "zod": "^3.25.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "ts-node": "^10.9.0",
+    "typescript": "^5.4.0"
+  },
+  "engines": { "node": ">=20.0.0" }
+}

package/templates/base/single/src/agents/my-agent.ts

@@ -0,0 +1,18 @@
+import type { AgentProfile } from '@backendkit-labs/agent-core';
+
+export const MY_AGENT_PROFILE: AgentProfile = {
+    id: 'my-agent',
+    name: 'My Agent',
+    icon: '🤖',
+    description: 'TODO: describe what this agent does',
+    delegatesTo: [],
+    allowedTools: [
+        'example_action',
+        'example_query',
+        // TODO: list the tool names this agent can use
+    ],
+    systemPrompt: `You are a helpful agent that TODO: <describe your domain>.
+
+Use the available tools to complete tasks requested by the user.
+Be precise and report results clearly.`,
+};

package/templates/base/single/src/config.ts

@@ -0,0 +1,18 @@
+import 'dotenv/config';
+
+export interface Config {
+    llmApiKey: string;
+    llmBaseUrl: string;
+    llmModel: string;
+}
+
+export function loadConfig(): Config {
+    const llmApiKey = process.env.LLM_API_KEY ?? '';
+    if (!llmApiKey) throw new Error('Missing LLM_API_KEY in environment');
+
+    return {
+        llmApiKey,
+        llmBaseUrl: process.env.LLM_BASE_URL ?? 'https://api.openai.com/v1',
+        llmModel:   process.env.LLM_MODEL   ?? 'gpt-4o',
+    };
+}

package/templates/base/single/src/engine.ts

@@ -0,0 +1,66 @@
+import * as os from 'os';
+import * as path from 'path';
+import {
+    AgentEngine,
+    AgentRegistry,
+    ToolRegistry,
+    ProviderRegistry,
+    CallbackTransport,
+    createMemorySystem,
+} from '@backendkit-labs/agent-core';
+import { OpenAICompatibleProvider } from './providers/openai-compatible';
+import { loadConfig } from './config';
+import { MY_AGENT_PROFILE } from './agents/my-agent';
+import { exampleAction, exampleQuery } from './tools/example-tools';
+
+// ── Persistent storage paths ──────────────────────────────────────────────────
+
+const APP_DIR = path.join(os.homedir(), '.my-agent');
+const HISTORY = path.join(APP_DIR, 'history.json');
+const MEM_DIR = path.join(APP_DIR, 'memory');
+
+// ── Memory system ─────────────────────────────────────────────────────────────
+
+const memory = createMemorySystem({
+    episodic:   { provider: 'json', path: path.join(MEM_DIR, 'episodes.json') },
+    semantic:   { provider: 'json', path: path.join(MEM_DIR, 'knowledge.json') },
+    procedural: { provider: 'json', path: path.join(MEM_DIR, 'patterns.json') },
+    retention:  { maxEpisodes: 500 },
+});
+
+export function createEngine(transport: CallbackTransport): AgentEngine {
+    const config = loadConfig();
+
+    const tools = new ToolRegistry();
+    tools
+        .register(exampleAction)
+        .register(exampleQuery);
+    for (const t of memory.getTools()) tools.register(t);
+    // TODO: register more tools
+
+    const agents = new AgentRegistry();
+    agents.register(MY_AGENT_PROFILE);
+    // TODO: register more specialists
+
+    const providers = new ProviderRegistry();
+    providers.register('default', new OpenAICompatibleProvider({
+        apiKey:  config.llmApiKey,
+        baseUrl: config.llmBaseUrl,
+        model:   config.llmModel,
+    }));
+
+    return new AgentEngine({
+        model:            { provider: 'default', id: config.llmModel },
+        agents,
+        tools,
+        providers,
+        defaultProvider:  'default',
+        defaultAgentId:   'my-agent',
+        transport,
+        maxIterations:    20,
+        iterationMode:    'auto',
+        historyPath:      HISTORY,
+        maxContextMessages: 100,
+        memorySystem:     memory,
+    });
+}

package/templates/base/single/src/providers/openai-compatible.ts

@@ -0,0 +1,104 @@
+import OpenAI from 'openai';
+import type { LLMProvider, LLMMessage, LLMStreamCallbacks, ToolDefinition } from '@backendkit-labs/agent-core';
+
+export interface OpenAICompatibleProviderOptions {
+    apiKey: string;
+    baseUrl: string;
+    model: string;
+    maxRetries?: number;
+}
+
+function isRetryable(err: unknown): boolean {
+    if (err && typeof err === 'object' && 'status' in err) {
+        const s = (err as { status: number }).status;
+        return s === 429 || s >= 500;
+    }
+    return false;
+}
+
+const sleep = (ms: number) => new Promise<void>(r => setTimeout(r, ms));
+
+export class OpenAICompatibleProvider implements LLMProvider {
+    private readonly client: OpenAI;
+    private readonly model: string;
+    private readonly maxRetries: number;
+
+    constructor(opts: OpenAICompatibleProviderOptions) {
+        this.client     = new OpenAI({ apiKey: opts.apiKey, baseURL: opts.baseUrl, maxRetries: 0 });
+        this.model      = opts.model;
+        this.maxRetries = opts.maxRetries ?? 3;
+    }
+
+    async chat(messages: LLMMessage[], tools: ToolDefinition[], callbacks: LLMStreamCallbacks): Promise<void> {
+        const oaiTools = tools.map(t => ({
+            type: 'function' as const,
+            function: { name: t.name, description: t.description, parameters: t.parameters },
+        })) as OpenAI.Chat.ChatCompletionTool[];
+
+        let attempt = 0;
+        let emitted = false;
+
+        while (attempt < this.maxRetries) {
+            attempt++;
+            try {
+                await this.stream(messages, oaiTools, {
+                    ...callbacks,
+                    onChunk: (d) => { emitted = true; callbacks.onChunk?.(d); },
+                });
+                return;
+            } catch (err) {
+                if (emitted || !isRetryable(err) || attempt >= this.maxRetries) {
+                    callbacks.onError(err instanceof Error ? err : new Error(String(err)));
+                    return;
+                }
+                await sleep(Math.min(1000 * 2 ** attempt, 16_000));
+            }
+        }
+    }
+
+    private async stream(
+        messages: LLMMessage[],
+        oaiTools: OpenAI.Chat.ChatCompletionTool[],
+        callbacks: LLMStreamCallbacks,
+    ): Promise<void> {
+        const stream = await this.client.chat.completions.create({
+            model: this.model,
+            messages: messages as OpenAI.Chat.ChatCompletionMessageParam[],
+            tools:       oaiTools.length ? oaiTools : undefined,
+            tool_choice: oaiTools.length ? 'auto'   : undefined,
+            stream: true,
+            stream_options: { include_usage: true },
+        });
+
+        let content = '';
+        const toolBuffers = new Map<number, { id: string; name: string; args: string }>();
+
+        for await (const chunk of stream) {
+            if (chunk.usage) callbacks.onMetrics?.(chunk.usage.prompt_tokens, chunk.usage.completion_tokens);
+            const delta = chunk.choices[0]?.delta;
+            if (!delta) continue;
+            if (delta.content) { content += delta.content; callbacks.onChunk?.(delta.content); }
+            if (delta.tool_calls) {
+                for (const tc of delta.tool_calls) {
+                    if (!toolBuffers.has(tc.index)) toolBuffers.set(tc.index, { id: '', name: '', args: '' });
+                    const buf = toolBuffers.get(tc.index)!;
+                    if (tc.id) buf.id = tc.id;
+                    if (tc.function?.name)      buf.name += tc.function.name;
+                    if (tc.function?.arguments) buf.args += tc.function.arguments;
+                }
+            }
+        }
+
+        const toolCalls = [...toolBuffers.entries()]
+            .sort(([a], [b]) => a - b)
+            .map(([, b]) => ({ id: b.id, type: 'function' as const, function: { name: b.name, arguments: b.args } }));
+
+        for (const tc of toolCalls) callbacks.onToolCall?.(tc.function.name, tc.function.arguments, tc.id);
+
+        callbacks.onDone({
+            role: 'assistant',
+            content: content || null,
+            tool_calls: toolCalls.length ? toolCalls : undefined,
+        });
+    }
+}

package/templates/base/single/src/tools/example-tools.ts

@@ -0,0 +1,28 @@
+import { defineTool, z } from '@backendkit-labs/agent-core';
+
+// TODO: Replace these with tools that call your actual domain SDK/API
+
+export const exampleAction = defineTool({
+    name: 'example_action',
+    description: 'TODO: describe what this tool does',
+    input: z.object({
+        target: z.string().describe('Target to act on'),
+        // TODO: add more parameters
+    }),
+    execute: async ({ target }) => {
+        // TODO: implement the actual action
+        return `Action executed on: ${target}`;
+    },
+});
+
+export const exampleQuery = defineTool({
+    name: 'example_query',
+    description: 'TODO: describe what this query returns',
+    input: z.object({
+        filter: z.string().optional().describe('Optional filter'),
+    }),
+    execute: async ({ filter }) => {
+        // TODO: implement the actual query
+        return JSON.stringify({ results: [], filter });
+    },
+});

package/templates/base/single/tsconfig.json

@@ -0,0 +1,17 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "commonjs",
+    "moduleResolution": "node",
+    "lib": ["ES2022"],
+    "types": ["node"],
+    "outDir": "dist",
+    "rootDir": "src",
+    "strict": true,
+    "skipLibCheck": true,
+    "esModuleInterop": true,
+    "resolveJsonModule": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}

package/templates/deploy/hybrid/src/index.ts

@@ -0,0 +1,27 @@
+import * as readline from 'readline';
+import { CallbackTransport } from '@backendkit-labs/agent-core';
+import { createEngine } from './engine';
+
+const transport = new CallbackTransport((event) => {
+    if (event.type === 'token')        process.stdout.write(event.content);
+    if (event.type === 'tool_call')    console.log(`\n⚙  ${event.name}`);
+    if (event.type === 'agent_switch') console.log(`\n→ ${event.to_name ?? event.to}`);
+    if (event.type === 'block_end')    console.log();
+    if (event.type === 'error')        console.error(`\nError: ${event.message}`);
+});
+
+const engine = createEngine(transport);
+
+const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+
+function prompt() {
+    rl.question('\n> ', async (input) => {
+        const trimmed = input.trim();
+        if (!trimmed || trimmed === '/exit') { rl.close(); return; }
+        await engine.run(trimmed);
+        prompt();
+    });
+}
+
+console.log('Agent ready. Type your request or /exit to quit.\n');
+prompt();

package/templates/deploy/hybrid/src/server.ts

@@ -0,0 +1,26 @@
+import 'dotenv/config';
+import { AgentMCPServer } from '@backendkit-labs/mcp-server';
+import { CallbackTransport } from '@backendkit-labs/agent-core';
+import { z } from 'zod';
+import { createEngine } from './engine';
+
+const server = new AgentMCPServer({
+    name:    process.env.npm_package_name ?? 'my-agent',
+    version: '1.0.0',
+    port:    parseInt(process.env.MCP_PORT ?? '3001'),
+
+    tools: [
+        {
+            name:        'agent_request',
+            description: 'TODO: describe what requests this agent handles',
+            schema: {
+                request: z.string().describe('Natural-language request for the agent'),
+            },
+            buildPrompt: ({ request }: { request: string }) => request,
+        },
+    ],
+
+    engineFactory: (transport: CallbackTransport) => createEngine(transport),
+});
+
+void (async () => { await server.start(); })();

package/templates/deploy/mcp-http/src/server.ts

@@ -0,0 +1,26 @@
+import 'dotenv/config';
+import { AgentMCPServer } from '@backendkit-labs/mcp-server';
+import { CallbackTransport } from '@backendkit-labs/agent-core';
+import { z } from 'zod';
+import { createEngine } from './engine';
+
+const server = new AgentMCPServer({
+    name:    process.env.npm_package_name ?? 'my-agent',
+    version: '1.0.0',
+    port:    parseInt(process.env.MCP_PORT ?? '3001'),
+
+    tools: [
+        {
+            name:        'agent_request',
+            description: 'TODO: describe what requests this agent handles',
+            schema: {
+                request: z.string().describe('Natural-language request for the agent'),
+            },
+            buildPrompt: ({ request }: { request: string }) => request,
+        },
+    ],
+
+    engineFactory: (transport: CallbackTransport) => createEngine(transport),
+});
+
+void (async () => { await server.start(); })();

package/templates/deploy/mcp-stdio/src/server.ts

@@ -0,0 +1,25 @@
+import 'dotenv/config';
+import { AgentMCPServer } from '@backendkit-labs/mcp-server';
+import { CallbackTransport } from '@backendkit-labs/agent-core';
+import { z } from 'zod';
+import { createEngine } from './engine';
+
+const server = new AgentMCPServer({
+    name:    process.env.npm_package_name ?? 'my-agent',
+    version: '1.0.0',
+
+    tools: [
+        {
+            name:        'agent_request',
+            description: 'TODO: describe what requests this agent handles',
+            schema: {
+                request: z.string().describe('Natural-language request for the agent'),
+            },
+            buildPrompt: ({ request }: { request: string }) => request,
+        },
+    ],
+
+    engineFactory: (transport: CallbackTransport) => createEngine(transport),
+});
+
+void (async () => { await server.startStdio(); })();

package/templates/deploy/repl/src/index.ts

@@ -0,0 +1,27 @@
+import * as readline from 'readline';
+import { CallbackTransport } from '@backendkit-labs/agent-core';
+import { createEngine } from './engine';
+
+const transport = new CallbackTransport((event) => {
+    if (event.type === 'token')        process.stdout.write(event.content);
+    if (event.type === 'tool_call')    console.log(`\n⚙  ${event.name}`);
+    if (event.type === 'agent_switch') console.log(`\n→ ${event.to_name ?? event.to}`);
+    if (event.type === 'block_end')    console.log();
+    if (event.type === 'error')        console.error(`\nError: ${event.message}`);
+});
+
+const engine = createEngine(transport);
+
+const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+
+function prompt() {
+    rl.question('\n> ', async (input) => {
+        const trimmed = input.trim();
+        if (!trimmed || trimmed === '/exit') { rl.close(); return; }
+        await engine.run(trimmed);
+        prompt();
+    });
+}
+
+console.log('Agent ready. Type your request or /exit to quit.\n');
+prompt();