create-bk-agent 0.22.6 → 0.22.8

package/README.md

@@ -1,272 +1,280 @@
-# create-bk-agent
-
-> **Status: `stable`** — Maintained and production-ready. No new features during the pilot phase.
-
-CLI scaffolding tool for the BackendKit Labs agent framework. Generates a fully configured TypeScript agent project in seconds — choose your architecture, deployment mode, and LLM provider, and get a working project with all dependencies wired.
-
-## Usage
-
-```bash
-npm create bk-agent@latest my-agent
-cd my-agent && npm install && npm run dev
-
-# Or with npx:
-npx create-bk-agent my-agent
-```
-
----
-
-## Interactive setup
-
-The CLI asks three questions:
-
-1. **Architecture** — what kind of agent?
-2. **Deploy mode** — how will it be used?
-3. **Provider** — which LLM API?
-
----
-
-## Architectures
-
-### `multi-agent` — Multi-agent orchestrator
-
-A routing orchestrator that delegates tasks to specialized sub-agents. Best for complex domains with distinct request types.
-
-```
-src/
-├── agents/         ← agent profiles (JSON)
-├── tools/          ← typed tool definitions
-├── orchestrator.ts ← routes requests to sub-agents
-└── index.ts
-```
-
-**Use case:** A customer platform with separate agents for billing, support, and account management.
-
-### `single` — Single-agent assistant
-
-One agent with a custom system prompt and your tools.
-
-```
-src/
-├── tools/
-├── agent.ts
-└── index.ts
-```
-
-### `coding` — Coding assistant
-
-Pre-configured with 10 coding agents, filesystem tools, persistent memory, and stack detection. Ready to use immediately.
-
-```
-src/
-└── index.ts    ← createCodingEngine() + readline REPL
-AGENT.md        ← project context injected into every LLM call
-```
-
-**Use case:** A project-specific coding assistant with your team's conventions in `AGENT.md`.
-
-### `autonomous` — Autonomous daemon
-
-Runs on a schedule without user interaction. Pre-wired with `createAutonomousAgent` + cron trigger.
-
-```
-src/
-├── triggers/
-├── tools/
-└── index.ts    ← cron + event loop
-```
-
-**Use case:** Nightly reports, daily standups, automated monitoring.
-
-### `minimal` — Minimal / embedded
-
-Bare-bones template — just `AgentEngine`, one tool, one agent. Use when embedding an agent into an existing application or building a library.
-
-```
-src/
-└── index.ts    ← AgentEngine, bare minimum
-```
-
-### `enterprise` — Enterprise (local LLM + RAG)
-
-Full enterprise setup: Ollama LLM, Obsidian vault as knowledge base, six department agents (General, Support, HR, Sales, Finance, Ops), VaultWriter, and optionally an `AgentServer` web server.
-
-```
-src/
-├── server.ts       ← createEnterpriseSetup() + AgentServer
-└── agents/         ← 6 department profiles
-.env.example        ← VAULT_PATH, JWT_SECRET, PORT, OLLAMA_HOST
-```
-
----
-
-## Deploy modes
-
-| Mode | Description |
-|------|-------------|
-| `repl` | Terminal REPL — stdin/stdout |
-| `mcp-stdio` | MCP server over stdio (for Claude Desktop, agent-core) |
-| `mcp-http` | MCP server over HTTP (`npm run server`) |
-| `hybrid` | REPL + MCP server side-by-side |
-| `library` | Exports an engine factory, no I/O |
-| `web` | Fastify web server — chat + kanban (enterprise only) |
-
----
-
-## Provider options
-
-| Provider | Required env var |
-|----------|-----------------|
-| DeepSeek | `DEEPSEEK_API_KEY` |
-| OpenAI | `OPENAI_API_KEY` |
-| Anthropic | `ANTHROPIC_API_KEY` |
-| Ollama (local) | *(none — requires `ollama serve`)* |
-
-The scaffolded `.env.example` lists all required variables.
-
----
-
-## Scaffolded project structure
-
-### Coding assistant (simplest)
-
-```
-my-agent/
-├── src/
-│   └── index.ts      ← createCodingEngine() + readline REPL
-├── AGENT.md          ← project context (edit this!)
-├── package.json
-├── tsconfig.json
-└── .env.example
-```
-
-**`AGENT.md`** is injected into every LLM call. Describe your project, stack, and conventions:
-
-```markdown
-# My Project
-
-## Tech stack
-Node.js 20, TypeScript 5, Express 4, PostgreSQL 15
-
-## Conventions
-- All functions must have JSDoc
-- Tests use Jest + Supertest
-- Never use `any` — use `unknown`
-
-## Architecture
-REST API with repository pattern. DB access only via src/repositories/.
-```
-
-### Enterprise web server (most complete)
-
-```
-my-agent/
-├── src/
-│   ├── server.ts         ← createEnterpriseSetup() + AgentServer
-│   └── agents/           ← 6 department profiles
-├── .env.example          ← VAULT_PATH, OLLAMA_HOST, JWT_SECRET, PORT
-├── package.json          ← agent-enterprise + agent-web
-└── tsconfig.json
-```
-
----
-
-## Examples
-
-### Coding assistant
-
-```bash
-npx create-bk-agent my-dev-assistant
-# → coding → repl → deepseek
-
-cd my-dev-assistant
-cp .env.example .env
-# Edit .env: add DEEPSEEK_API_KEY
-
-# Describe your project
-nano AGENT.md
-
-npm install && npm run dev
-# > What can I help with?
-```
-
-### Enterprise on-premises assistant
-
-```bash
-npx create-bk-agent company-assistant
-# → enterprise → web → ollama
-
-cd company-assistant
-cp .env.example .env
-# Edit .env: VAULT_PATH=/path/to/obsidian-vault
-
-ollama serve
-ollama pull llama3.2
-ollama pull nomic-embed-text
-
-npm install && npm run dev
-# → Indexing vault...
-# → Server running on :4001
-# Chat:    http://localhost:4001/
-# Kanban:  http://localhost:4001/#kanban
-```
-
-### Autonomous cron agent
-
-```bash
-npx create-bk-agent standup-bot
-# → autonomous → repl → deepseek
-
-cd standup-bot
-# Edit src/triggers/index.ts: schedule, prompt, output
-npm install && npm run dev
-```
-
-### MCP server exposing your tools
-
-```bash
-npx create-bk-agent my-tools-server
-# → single → mcp-http → openai
-
-cd my-tools-server
-# Add tools to src/tools/
-# Add agent to src/agents/
-npm install && npm run server   # MCP server on :3000
-```
-
-Claude Desktop config:
-
-```json
-{
-  "mcpServers": {
-    "my-tools": {
-      "command": "npx",
-      "args": ["-y", "my-tools-server"]
-    }
-  }
-}
-```
-
----
-
-## `bk add` command
-
-After scaffolding, add new components to your project:
-
-```bash
-bk add tool lookup-order      # creates src/tools/lookup-order.ts
-bk add agent billing          # creates src/agents/billing.json
-bk add trigger daily-report   # adds a cron trigger
-```
-
----
-
-## Scripts in scaffolded projects
-
-| Script | Description |
-|--------|-------------|
-| `npm run dev` | Development with tsx / ts-node |
-| `npm run build` | Compile TypeScript |
-| `npm run start` | Run compiled output |
-| `npm run server` | Start MCP or web server |
-| `npm run typecheck` | TypeScript type-check only |
+# create-bk-agent
+
+> **Status: `stable`** — Maintained and production-ready. No new features during the pilot phase.
+
+CLI scaffolding tool for the BackendKit Labs agent framework. Generates a fully configured TypeScript agent project in seconds — choose your architecture, deployment mode, and LLM provider, and get a working project with all dependencies wired.
+
+## Usage
+
+```bash
+npm create bk-agent@latest my-agent
+cd my-agent && npm install && npm run dev
+
+# Or with npx:
+npx create-bk-agent my-agent
+```
+
+---
+
+## Interactive setup
+
+The CLI asks three questions:
+
+1. **Architecture** — what kind of agent?
+2. **Deploy mode** — how will it be used?
+3. **Provider** — which LLM API?
+
+---
+
+## Architectures
+
+### `multi-agent` — Multi-agent orchestrator
+
+A routing orchestrator that delegates tasks to specialized sub-agents. Best for complex domains with distinct request types.
+
+```
+src/
+├── agents/         ← agent profiles (JSON)
+├── tools/          ← typed tool definitions
+├── orchestrator.ts ← routes requests to sub-agents
+└── index.ts
+```
+
+**Use case:** A customer platform with separate agents for billing, support, and account management.
+
+### `single` — Single-agent assistant
+
+One agent with a custom system prompt and your tools.
+
+```
+src/
+├── tools/
+├── agent.ts
+└── index.ts
+```
+
+### `coding` — Coding assistant
+
+Pre-configured with 10 coding agents, filesystem tools, persistent memory, and stack detection. Ready to use immediately.
+
+```
+src/
+└── index.ts    ← createCodingEngine() + readline REPL
+AGENT.md        ← project context injected into every LLM call
+```
+
+**Use case:** A project-specific coding assistant with your team's conventions in `AGENT.md`.
+
+### `autonomous` — Autonomous daemon
+
+Runs on a schedule without user interaction. Pre-wired with `createAutonomousAgent` + cron trigger.
+
+```
+src/
+├── triggers/
+├── tools/
+└── index.ts    ← cron + event loop
+```
+
+**Use case:** Nightly reports, daily standups, automated monitoring.
+
+### `minimal` — Minimal / embedded
+
+Bare-bones template — just `AgentEngine`, one tool, one agent. Use when embedding an agent into an existing application or building a library.
+
+```
+src/
+└── index.ts    ← AgentEngine, bare minimum
+```
+
+### `enterprise` — Enterprise (local LLM + RAG)
+
+Full enterprise setup: Ollama LLM, Obsidian vault as knowledge base, six department agents (General, Support, HR, Sales, Finance, Ops), VaultWriter, and optionally an `AgentServer` web server.
+
+```
+src/
+├── server.ts       ← createEnterpriseSetup() + AgentServer
+└── agents/         ← 6 department profiles
+.env.example        ← VAULT_PATH, JWT_SECRET, PORT, OLLAMA_HOST
+```
+
+---
+
+## Deploy modes
+
+| Mode | Description |
+|------|-------------|
+| `repl` | Terminal REPL — stdin/stdout |
+| `mcp-stdio` | MCP server over stdio (for Claude Desktop, agent-core) |
+| `mcp-http` | MCP server over HTTP (`npm run server`) |
+| `hybrid` | REPL + MCP server side-by-side |
+| `library` | Exports an engine factory, no I/O |
+| `web` | Fastify web server — chat + kanban (enterprise only) |
+
+---
+
+## Provider options
+
+| Provider | Required env var |
+|----------|-----------------|
+| DeepSeek | `DEEPSEEK_API_KEY` |
+| OpenAI | `OPENAI_API_KEY` |
+| Anthropic | `ANTHROPIC_API_KEY` |
+| Ollama (local) | *(none — requires `ollama serve`)* |
+
+The scaffolded `.env.example` lists all required variables.
+
+---
+
+## Scaffolded project structure
+
+### Coding assistant (simplest)
+
+```
+my-agent/
+├── src/
+│   └── index.ts      ← createCodingEngine() + readline REPL
+├── AGENT.md          ← project context (edit this!)
+├── package.json
+├── tsconfig.json
+└── .env.example
+```
+
+**`AGENT.md`** is injected into every LLM call. Describe your project, stack, and conventions:
+
+```markdown
+# My Project
+
+## Tech stack
+Node.js 20, TypeScript 5, Express 4, PostgreSQL 15
+
+## Conventions
+- All functions must have JSDoc
+- Tests use Jest + Supertest
+- Never use `any` — use `unknown`
+
+## Architecture
+REST API with repository pattern. DB access only via src/repositories/.
+```
+
+### Enterprise web server (most complete)
+
+```
+my-agent/
+├── src/
+│   ├── server.ts         ← createEnterpriseSetup() + AgentServer
+│   └── agents/           ← 6 department profiles
+├── .env.example          ← VAULT_PATH, OLLAMA_HOST, JWT_SECRET, PORT
+├── package.json          ← agent-enterprise + agent-web
+└── tsconfig.json
+```
+
+---
+
+## Examples
+
+### Coding assistant
+
+```bash
+npx create-bk-agent my-dev-assistant
+# → coding → repl → deepseek
+
+cd my-dev-assistant
+cp .env.example .env
+# Edit .env: add DEEPSEEK_API_KEY
+
+# Describe your project
+nano AGENT.md
+
+npm install && npm run dev
+# > What can I help with?
+```
+
+### Enterprise on-premises assistant
+
+```bash
+npx create-bk-agent company-assistant
+# → enterprise → web → ollama
+
+cd company-assistant
+cp .env.example .env
+# Edit .env: VAULT_PATH=/path/to/obsidian-vault
+
+ollama serve
+ollama pull llama3.2
+ollama pull nomic-embed-text
+
+npm install && npm run dev
+# → Indexing vault...
+# → Server running on :4001
+# Chat:    http://localhost:4001/
+# Kanban:  http://localhost:4001/#kanban
+```
+
+### Autonomous cron agent
+
+```bash
+npx create-bk-agent standup-bot
+# → autonomous → repl → deepseek
+
+cd standup-bot
+# Edit src/triggers/index.ts: schedule, prompt, output
+npm install && npm run dev
+```
+
+### MCP server exposing your tools
+
+```bash
+npx create-bk-agent my-tools-server
+# → single → mcp-http → openai
+
+cd my-tools-server
+# Add tools to src/tools/
+# Add agent to src/agents/
+npm install && npm run server   # MCP server on :3000
+```
+
+Claude Desktop config:
+
+```json
+{
+  "mcpServers": {
+    "my-tools": {
+      "command": "npx",
+      "args": ["-y", "my-tools-server"]
+    }
+  }
+}
+```
+
+---
+
+## `bk add` command
+
+After scaffolding, add new components to your project:
+
+```bash
+bk add tool lookup-order      # creates src/tools/lookup-order.ts
+bk add agent billing          # creates src/agents/billing.json
+bk add trigger daily-report   # adds a cron trigger
+```
+
+### Tests that need no API key
+
+```bash
+npx create-bk-agent add testing
+```
+
+Adds `@backendkit-labs/agent-testkit`, jest and ts-jest as dev dependencies, a `jest.config.js`, a `test` script and an example test (`src/__tests__/agent.example.test.ts`) that runs an agent against a scripted provider. Existing files are never overwritten. See the [agent-testkit README](../testkit/README.md) for the mock LLM server, record/replay and the real-world assertions.
+
+---
+
+## Scripts in scaffolded projects
+
+| Script | Description |
+|--------|-------------|
+| `npm run dev` | Development with tsx / ts-node |
+| `npm run build` | Compile TypeScript |
+| `npm run start` | Run compiled output |
+| `npm run server` | Start MCP or web server |
+| `npm run typecheck` | TypeScript type-check only |

package/dist/src/add/index.js

@@ -8,39 +8,44 @@ const tools_1 = require("./modules/tools");
 const mcp_client_1 = require("./modules/mcp-client");
 const plugin_1 = require("./modules/plugin");
 const knowledge_1 = require("./modules/knowledge");
-const HELP = `
-Usage: npx create-bk-agent add <module> [options]
-
-Modules:
-  server                Add an HTTP MCP server (src/server.ts)
-    --port <n>            Port to listen on  (default: 3001)
-    --name <s>            MCP server name    (default: project directory name)
-
-  specialist <name>     Add a new specialist agent to a multi-agent project
-                        (creates src/agents/<name>.ts and patches engine.ts)
-
-  tools <domain>        Add a tool file for a new domain
-                        (creates src/tools/<domain>-tools.ts and patches engine.ts)
-
-  knowledge <path>      Add a folder or vault to the RAG knowledge base (enterprise agents)
-    --vault <path>        Register an entirely new Obsidian vault (instead of a subfolder)
-
-  mcp-client <url>      Add a remote MCP server to the engine
-    --name <s>            Name for the mcpServers entry (default: last URL segment)
-
-  plugin <name>         Install a backendkit agent as a stdio MCP plugin
-                        Available: docker, k8s
-
-Examples:
-  npx create-bk-agent add server --port 4000
-  npx create-bk-agent add specialist data-analyst
-  npx create-bk-agent add tools github
-  npx create-bk-agent add knowledge ./docs
-  npx create-bk-agent add knowledge "04-Recursos/Backend"
-  npx create-bk-agent add knowledge --vault "C:/Company/HR-Vault"
-  npx create-bk-agent add mcp-client http://localhost:3001/mcp --name billing
-  npx create-bk-agent add plugin docker
-  npx create-bk-agent add plugin k8s
+const testing_1 = require("./modules/testing");
+const HELP = `
+Usage: npx create-bk-agent add <module> [options]
+
+Modules:
+  server                Add an HTTP MCP server (src/server.ts)
+    --port <n>            Port to listen on  (default: 3001)
+    --name <s>            MCP server name    (default: project directory name)
+
+  specialist <name>     Add a new specialist agent to a multi-agent project
+                        (creates src/agents/<name>.ts and patches engine.ts)
+
+  tools <domain>        Add a tool file for a new domain
+                        (creates src/tools/<domain>-tools.ts and patches engine.ts)
+
+  knowledge <path>      Add a folder or vault to the RAG knowledge base (enterprise agents)
+    --vault <path>        Register an entirely new Obsidian vault (instead of a subfolder)
+
+  mcp-client <url>      Add a remote MCP server to the engine
+    --name <s>            Name for the mcpServers entry (default: last URL segment)
+
+  plugin <name>         Install a backendkit agent as a stdio MCP plugin
+                        Available: docker, k8s
+
+  testing               Set up tests that need no API key: agent-testkit + jest,
+                        a jest.config.js, a "test" script and an example test
+
+Examples:
+  npx create-bk-agent add server --port 4000
+  npx create-bk-agent add specialist data-analyst
+  npx create-bk-agent add tools github
+  npx create-bk-agent add knowledge ./docs
+  npx create-bk-agent add knowledge "04-Recursos/Backend"
+  npx create-bk-agent add knowledge --vault "C:/Company/HR-Vault"
+  npx create-bk-agent add mcp-client http://localhost:3001/mcp --name billing
+  npx create-bk-agent add plugin docker
+  npx create-bk-agent add plugin k8s
+  npx create-bk-agent add testing
 `;
 function runAdd(args, cwd) {
     const [module, ...rest] = args;
@@ -78,6 +83,9 @@ function runAdd(args, cwd) {
         case 'knowledge':
             (0, knowledge_1.addKnowledge)(info, rest);
             break;
+        case 'testing':
+            (0, testing_1.addTesting)(info, rest);
+            break;
         default:
             console.error(`\n✗  Unknown module: "${module}"\n`);
             console.log(HELP);

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

@@ -0,0 +1,116 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EXAMPLE_TEST = void 0;
+exports.addTesting = addTesting;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const child_process_1 = require("child_process");
+const patcher_1 = require("../patcher");
+const scaffold_1 = require("../../scaffold");
+const DEV_DEPS = [
+    ['@backendkit-labs/agent-testkit', scaffold_1.GENERATED_DEP_RANGES['@backendkit-labs/agent-testkit']],
+    ['jest', '^29.0.0'],
+    ['ts-jest', '^29.0.0'],
+    ['@types/jest', '^29.0.0'],
+];
+const JEST_CONFIG = `/** @type {import('jest').Config} */
+module.exports = {
+    preset: 'ts-jest',
+    testEnvironment: 'node',
+    testMatch: ['**/__tests__/**/*.test.ts'],
+};
+`;
+exports.EXAMPLE_TEST = `import { createBaseEngine } from '@backendkit-labs/agent-core';
+import { mockTransport, scriptedProvider } from '@backendkit-labs/agent-testkit';
+
+// Test an agent without an API key. This example builds its own small engine; to test your project's agent,
+// export a factory from src/engine.ts that accepts a provider and pass the doubles below instead.
+//
+// More doubles in @backendkit-labs/agent-testkit:
+//   - startMockLlmServer(...)  a fake OpenAI-compatible server that returns 429s, resets, overflows...
+//   - RecordingProvider / ReplayProvider  record a real run once, replay it in every test run
+//   - world.fileEquals / untouched / processGone  check what the agent really did to the system
+
+const agent = {
+    id: 'helper', name: 'Helper', icon: '🤖', description: 'example agent',
+    systemPrompt: 'Answer briefly.', allowedTools: [], delegatesTo: [],
+};
+
+describe('an agent tested without an API key', () => {
+    it('answers from a scripted provider', async () => {
+        const t = mockTransport();
+        const engine = createBaseEngine({
+            providers: { mock: scriptedProvider([{ content: 'Hello from the script' }]) },
+            defaultProvider: 'mock', agents: [agent], defaultAgent: 'helper',
+            transport: t.transport, workingDir: process.cwd(), noQA: true, iterationMode: 'auto',
+        });
+
+        await engine.run('hi');
+
+        expect(t.text()).toBe('Hello from the script');
+        expect(t.eventsOf('error')).toEqual([]);
+    });
+});
+`;
+/** \`add testing\`: dev dependencies, a jest config, a \`test\` script and an example test. Never overwrites files. */
+function addTesting(info, _args, opts = {}) {
+    const install = opts.install ?? true;
+    let added = false;
+    for (const [name, range] of DEV_DEPS)
+        added = (0, patcher_1.addPackageDevDependency)(info.pkgFile, name, range) || added;
+    (0, patcher_1.addPackageScript)(info.pkgFile, 'test', 'jest');
+    const written = [];
+    const write = (rel, content) => {
+        const target = path.join(info.cwd, rel);
+        if (fs.existsSync(target))
+            return;
+        fs.mkdirSync(path.dirname(target), { recursive: true });
+        fs.writeFileSync(target, content);
+        written.push(rel);
+    };
+    if (!fs.existsSync(path.join(info.cwd, 'jest.config.js')) && !fs.existsSync(path.join(info.cwd, 'jest.config.ts'))) {
+        write('jest.config.js', JEST_CONFIG);
+    }
+    write(path.join('src', '__tests__', 'agent.example.test.ts'), exports.EXAMPLE_TEST);
+    if (added && install) {
+        console.log('\n  Installing test dependencies...');
+        (0, child_process_1.execSync)('npm install', { cwd: info.cwd, stdio: 'inherit' });
+    }
+    console.log('\n  ✅ Testing set up.\n');
+    for (const f of written)
+        console.log(`     created ${f}`);
+    console.log('     run: npm test\n');
+}

package/dist/src/add/patcher.js

@@ -38,6 +38,7 @@ exports.insertAfterPattern = insertAfterPattern;
 exports.insertBeforePattern = insertBeforePattern;
 exports.addPackageScript = addPackageScript;
 exports.addPackageDependency = addPackageDependency;
+exports.addPackageDevDependency = addPackageDevDependency;
 exports.addMcpServerEntry = addMcpServerEntry;
 exports.addMcpStdioEntry = addMcpStdioEntry;
 const fs = __importStar(require("fs"));
@@ -123,6 +124,16 @@ function addPackageDependency(pkgFile, depName, version) {
     fs.writeFileSync(pkgFile, JSON.stringify(pkg, null, 2) + '\n');
     return true;
 }
+/** Adds `depName@version` to devDependencies if it is in neither dependencies nor devDependencies. */
+function addPackageDevDependency(pkgFile, depName, version) {
+    const pkg = JSON.parse(fs.readFileSync(pkgFile, 'utf-8'));
+    if (pkg.dependencies?.[depName] || pkg.devDependencies?.[depName])
+        return false;
+    pkg.devDependencies ??= {};
+    pkg.devDependencies[depName] = version;
+    fs.writeFileSync(pkgFile, JSON.stringify(pkg, null, 2) + '\n');
+    return true;
+}
 // ── AgentEngine options patcher ───────────────────────────────────────────────
 /**
  * Adds `mcpServers: [{ name, url }]` to the first AgentEngine constructor call.

package/dist/src/scaffold.js

@@ -69,6 +69,7 @@ function copyDir(src, dst) {
 exports.GENERATED_DEP_RANGES = {
     '@backendkit-labs/mcp-server': '^0.16.0',
     '@backendkit-labs/agent-web': '^0.4.0',
+    '@backendkit-labs/agent-testkit': '^0.1.0',
 };
 // ── Patch package.json — name + scripts ──────────────────────────────────────
 const DEPLOY_SCRIPTS = {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-bk-agent",
-  "version": "0.22.6",
+  "version": "0.22.8",
   "description": "Create a new BackendKit agent project",
   "main": "dist/src/index.js",
   "bin": {
@@ -28,7 +28,7 @@
     "test": "jest"
   },
   "peerDependencies": {
-    "@backendkit-labs/agent-core": ">=0.24.0 <0.29.0"
+    "@backendkit-labs/agent-core": ">=0.24.0 <0.30.0"
   },
   "peerDependenciesMeta": {
     "@backendkit-labs/agent-core": {

package/templates/autonomous/package.json

@@ -11,7 +11,7 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@backendkit-labs/agent-core": "^0.28.0",
+    "@backendkit-labs/agent-core": "^0.29.0",
     "dotenv": "^16.0.0"
   },
   "devDependencies": {

package/templates/base/autonomous/package.json

@@ -11,7 +11,7 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@backendkit-labs/agent-core": "^0.28.0",
+    "@backendkit-labs/agent-core": "^0.29.0",
     "dotenv": "^16.0.0"
   },
   "devDependencies": {

package/templates/base/coding/package.json

@@ -11,8 +11,8 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@backendkit-labs/agent-coding": "^0.24.0",
-    "@backendkit-labs/agent-core": "^0.28.0",
+    "@backendkit-labs/agent-coding": "^0.25.0",
+    "@backendkit-labs/agent-core": "^0.29.0",
     "dotenv": "^16.0.0"
   },
   "devDependencies": {

package/templates/base/enterprise/package.json

@@ -12,9 +12,9 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@backendkit-labs/agent-core": "^0.28.0",
-    "@backendkit-labs/agent-coding": "^0.24.0",
-    "@backendkit-labs/agent-enterprise": "^0.5.0",
+    "@backendkit-labs/agent-core": "^0.29.0",
+    "@backendkit-labs/agent-coding": "^0.25.0",
+    "@backendkit-labs/agent-enterprise": "^0.6.0",
     "dotenv": "^16.0.0",
     "zod": "^3.25.0"
   },

package/templates/base/minimal/package.json

@@ -11,7 +11,7 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@backendkit-labs/agent-core": "^0.28.0",
+    "@backendkit-labs/agent-core": "^0.29.0",
     "dotenv": "^16.0.0"
   },
   "devDependencies": {

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

@@ -12,7 +12,7 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@backendkit-labs/agent-core": "^0.28.0",
+    "@backendkit-labs/agent-core": "^0.29.0",
     "dotenv": "^16.0.0",
     "openai": "^4.0.0",
     "zod": "^3.25.0"

package/templates/base/single/package.json

@@ -12,7 +12,7 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@backendkit-labs/agent-core": "^0.28.0",
+    "@backendkit-labs/agent-core": "^0.29.0",
     "dotenv": "^16.0.0",
     "openai": "^4.0.0",
     "zod": "^3.25.0"

package/templates/coding/package.json

@@ -11,8 +11,8 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@backendkit-labs/agent-coding": "^0.24.0",
-    "@backendkit-labs/agent-core": "^0.28.0",
+    "@backendkit-labs/agent-coding": "^0.25.0",
+    "@backendkit-labs/agent-core": "^0.29.0",
     "dotenv": "^16.0.0"
   },
   "devDependencies": {

package/templates/domain-agent/package.json

@@ -11,7 +11,7 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@backendkit-labs/agent-core": "^0.28.0",
+    "@backendkit-labs/agent-core": "^0.29.0",
     "dotenv": "^16.0.0",
     "openai": "^4.0.0",
     "zod": "^3.25.0"

package/templates/mcp-server/package.json

@@ -12,7 +12,7 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@backendkit-labs/agent-core": "^0.28.0",
+    "@backendkit-labs/agent-core": "^0.29.0",
     "@modelcontextprotocol/sdk": "^1.12.0",
     "dotenv": "^16.0.0",
     "zod": "^3.25.0"

package/templates/minimal/package.json

@@ -11,7 +11,7 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@backendkit-labs/agent-core": "^0.28.0",
+    "@backendkit-labs/agent-core": "^0.29.0",
     "dotenv": "^16.0.0"
   },
   "devDependencies": {