@backendkit-labs/agent-coding 0.19.2 → 0.19.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +407 -107
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -1,178 +1,478 @@
1
1
  # @backendkit-labs/agent-coding
2
2
 
3
- Coding agent for the BackendKit agent framework — 10 specialized agents, file tools, git integration, LLM providers.
3
+ A production-ready coding agent engine built on `@backendkit-labs/agent-core`. Bundles 10 specialized agents, filesystem tools, multi-provider support (DeepSeek, OpenAI, Anthropic, Ollama, Kimi, Grok), automatic stack detection, persistent memory, QA review, reflection, and an orchestration pipeline — all in a single `createCodingEngine()` call.
4
+
5
+ [![npm](https://img.shields.io/npm/v/@backendkit-labs/agent-coding)](https://www.npmjs.com/package/@backendkit-labs/agent-coding)
6
+
7
+ ## Table of contents
8
+
9
+ - [Installation](#installation)
10
+ - [Quick start](#quick-start)
11
+ - [createCodingEngine](#createcodingengine)
12
+ - [createCodingEngineFromConfig](#createcodingenginefromconfig)
13
+ - [Providers](#providers)
14
+ - [Built-in agents](#built-in-agents)
15
+ - [Built-in tools](#built-in-tools)
16
+ - [Skill packs](#skill-packs)
17
+ - [Orchestration pipeline](#orchestration-pipeline)
18
+ - [Reflection engine](#reflection-engine)
19
+ - [MCP server integration](#mcp-server-integration)
20
+ - [Multi-agent examples](#multi-agent-examples)
21
+ - [Config file](#config-file)
22
+
23
+ ---
24
+
25
+ ## Installation
4
26
 
5
27
  ```bash
6
28
  npm install @backendkit-labs/agent-coding
7
29
  ```
8
30
 
9
- > **Quickstart**: `npx create-bk-agent my-project` — scaffolds a complete project in seconds.
31
+ All provider adapters are bundled — no separate packages needed.
10
32
 
11
33
  ---
12
34
 
13
- ## Usage
35
+ ## Quick start
14
36
 
15
- ```ts
37
+ ```typescript
16
38
  import { createCodingEngine } from '@backendkit-labs/agent-coding';
17
- import { CallbackTransport } from '@backendkit-labs/agent-core';
18
-
19
- const transport = new CallbackTransport((event) => {
20
- if (event.type === 'token') process.stdout.write(event.content);
21
- });
22
39
 
23
40
  const engine = createCodingEngine({
24
- providers: { anthropic: { apiKey: process.env.ANTHROPIC_API_KEY! } },
25
- defaultProvider: 'anthropic',
26
- workingDir: process.cwd(),
27
- appName: 'my-agent',
28
- transport,
41
+ providers: { deepseek: { apiKey: process.env.DEEPSEEK_API_KEY! } },
42
+ defaultProvider: 'deepseek',
29
43
  });
30
44
 
31
- await engine.run('Add error handling to src/api/users.ts');
45
+ await engine.run('List all TypeScript files in src/ and tell me which ones have no tests');
32
46
  ```
33
47
 
48
+ That single call gives you: 10 specialized agents, filesystem tools (read/write/edit/search), persistent project memory, skill loading, and stack auto-detection.
49
+
34
50
  ---
35
51
 
36
- ## Providers
52
+ ## createCodingEngine
53
+
54
+ The primary factory. Returns a fully configured `AgentEngine`.
55
+
56
+ ### Options reference
57
+
58
+ ```typescript
59
+ interface CodingEngineOptions {
60
+ // Required
61
+ providers: ProvidersConfig;
62
+ defaultProvider: string;
63
+
64
+ // Agents and engine
65
+ defaultAgent?: string; // default: 'general'
66
+ workingDir?: string; // default: process.cwd()
67
+ maxIterations?: number; // default: 100
68
+ maxParallelAgents?: number; // default: 6
37
69
 
38
- ```ts
39
- import {
40
- AnthropicProvider,
41
- OllamaProvider,
42
- OpenAICompatibleProvider,
43
- } from '@backendkit-labs/agent-coding';
70
+ // I/O
71
+ transport?: Transport; // default: StdoutTransport
44
72
 
45
- // Anthropic (Claude)
46
- new AnthropicProvider(apiKey, model?)
73
+ // App identity
74
+ appName?: string; // default: 'bk-agent' — used for ~/.{appName}/
47
75
 
48
- // Ollama — local LLM, no API key required
49
- new OllamaProvider({ host?: string, model?: string })
50
- // host default: http://localhost:11434
51
- // model default: llama3.2
52
- // checkConnection() verifies Ollama is running before first use
76
+ // Persistence
77
+ disablePersistence?: boolean; // skip ProjectStore (useful for testing)
53
78
 
54
- // OpenAI / DeepSeek / any OpenAI-compatible API
55
- new OpenAICompatibleProvider({ apiKey, baseUrl, model })
79
+ // MCP servers
80
+ mcpServers?: MCPServerConfig[];
81
+
82
+ // Context sharing
83
+ subAgentContextMessages?: number; // messages visible to sub-agents (recommend 10-20)
84
+
85
+ // Iteration control
86
+ onToolApproval?: (toolName, agentId, argsPreview) => Promise<ToolApprovalDecision>;
87
+ onIterationLimit?: (stats: IterationStats) => Promise<boolean>;
88
+ onStep?: (stats: IterationStats) => Promise<boolean>;
89
+
90
+ // Orchestration
91
+ orchestration?: boolean | OrchestrationOptions;
92
+ }
56
93
  ```
57
94
 
58
- **Local-first setup with Ollama:**
95
+ ### Minimal setup
59
96
 
60
- ```ts
61
- import { OllamaProvider } from '@backendkit-labs/agent-coding';
97
+ ```typescript
98
+ const engine = createCodingEngine({
99
+ providers: { deepseek: { apiKey: 'sk-...' } },
100
+ defaultProvider: 'deepseek',
101
+ });
102
+ ```
62
103
 
104
+ ### Multiple providers
105
+
106
+ ```typescript
63
107
  const engine = createCodingEngine({
64
- providers: { local: new OllamaProvider({ model: 'qwen2.5-coder:7b' }) },
65
- defaultProvider: 'local',
66
- workingDir: process.cwd(),
67
- appName: 'my-agent',
68
- transport,
108
+ providers: {
109
+ deepseek: { apiKey: process.env.DEEPSEEK_API_KEY! },
110
+ anthropic: { apiKey: process.env.ANTHROPIC_API_KEY!, model: 'claude-opus-4-8' },
111
+ ollama: { host: 'http://localhost:11434', model: 'llama3.2' },
112
+ },
113
+ defaultProvider: 'deepseek',
114
+ // Each agent profile can specify a provider override
115
+ });
116
+ ```
117
+
118
+ ### With full orchestration
119
+
120
+ ```typescript
121
+ const engine = createCodingEngine({
122
+ providers: { deepseek: { apiKey: '...' } },
123
+ defaultProvider: 'deepseek',
124
+ orchestration: true,
125
+ // Enables:
126
+ // intent detection → domain detection → risk scoring
127
+ // policy engine → agent routing → QA auto-review → reflection
128
+ });
129
+ ```
130
+
131
+ ### With MCP servers
132
+
133
+ ```typescript
134
+ const engine = createCodingEngine({
135
+ providers: { openai: { apiKey: '...' } },
136
+ defaultProvider: 'openai',
137
+ mcpServers: [
138
+ { name: 'github', command: 'npx', args: ['-y', '@modelcontextprotocol/server-github'], env: { GITHUB_TOKEN: '...' } },
139
+ { name: 'postgres', command: 'npx', args: ['-y', '@modelcontextprotocol/server-postgres'], env: { DATABASE_URL: '...' } },
140
+ ],
141
+ subAgentContextMessages: 15,
142
+ });
143
+ ```
144
+
145
+ ### With manual tool approval
146
+
147
+ ```typescript
148
+ const engine = createCodingEngine({
149
+ providers: { deepseek: { apiKey: '...' } },
150
+ defaultProvider: 'deepseek',
151
+ onToolApproval: async (toolName, agentId, argsPreview) => {
152
+ const write = ['write_file', 'edit_file', 'run_command'];
153
+ if (!write.includes(toolName)) return 'approve';
154
+ console.log(`\n⚠ [${agentId}] ${toolName}:\n${argsPreview}\n`);
155
+ const a = await prompt('Approve? (y/n/all): ');
156
+ if (a === 'y') return 'approve';
157
+ if (a === 'all') return 'approve_all';
158
+ return 'reject';
159
+ },
69
160
  });
70
161
  ```
71
162
 
72
163
  ---
73
164
 
74
- ## Built-in agents (10)
165
+ ## createCodingEngineFromConfig
75
166
 
76
- | Agent | ID | Specialty | Recommended model tier |
77
- |---|---|---|---|
78
- | General | `general` | Orchestrator — routes to specialists | smart |
79
- | Architecture | `architecture` | Design, patterns, ADRs | smart |
80
- | Security | `security` | Vulnerabilities, hardening | smart |
81
- | Project Manager | `project-manager` | /init workflow, planning | smart |
82
- | Coder | `coder` | Implementation, bulk edits | fast |
83
- | Backend | `backend` | APIs, databases, services | fast |
84
- | Frontend | `frontend` | UI, components, CSS | fast |
85
- | QA Engineer | `qa-engineer` | Tests, edge cases, code review | fast |
86
- | Infrastructure | `infrastructure` | Docker, CI/CD, cloud | fast |
87
- | Data | `data` | Pipelines, models, queries | fast |
167
+ Reads credentials from `~/.{appName}/config.json`. No code changes needed to switch providers:
88
168
 
89
- "Smart" agents reason and route — use a thinking/reasoning model. "Fast" agents execute tool calls in loops — use a cheap, low-latency model. See [per-agent model overrides](#per-agent-model-overrides) below.
169
+ ```typescript
170
+ import { createCodingEngineFromConfig } from '@backendkit-labs/agent-coding';
171
+
172
+ const engine = createCodingEngineFromConfig();
173
+
174
+ // With overrides
175
+ const engine = createCodingEngineFromConfig({
176
+ workingDir: '/my-project',
177
+ orchestration: true,
178
+ });
179
+ ```
90
180
 
91
181
  ---
92
182
 
93
- ## Built-in tools
183
+ ## Providers
184
+
185
+ ### DeepSeek
186
+
187
+ ```typescript
188
+ providers: {
189
+ deepseek: {
190
+ apiKey: process.env.DEEPSEEK_API_KEY!,
191
+ model?: 'deepseek-chat', // default
192
+ maxTokens?: 8192,
193
+ temperature?: 0.7,
194
+ }
195
+ }
196
+ ```
197
+
198
+ ### OpenAI
199
+
200
+ ```typescript
201
+ providers: {
202
+ openai: {
203
+ apiKey: process.env.OPENAI_API_KEY!,
204
+ model?: 'gpt-4o',
205
+ baseUrl?: 'https://api.openai.com/v1',
206
+ }
207
+ }
208
+ ```
209
+
210
+ ### Anthropic (Claude)
211
+
212
+ ```typescript
213
+ providers: {
214
+ anthropic: {
215
+ apiKey: process.env.ANTHROPIC_API_KEY!,
216
+ model?: 'claude-sonnet-4-6', // default
217
+ }
218
+ }
219
+ ```
94
220
 
95
- File operations (`read_file`, `write_file`, `edit_file`, `list_directory`, `search_files`),
96
- command execution (`run_command`), memory (`save_learning`, `save_context`, `update_session`),
97
- audit trail (`save_audit`).
221
+ ### Ollama (local — no API key)
98
222
 
99
- All file tools are sandboxed to `workingDir` — path traversal is blocked at the framework level.
223
+ ```bash
224
+ # Prerequisites
225
+ ollama serve
226
+ ollama pull llama3.2
227
+ ```
228
+
229
+ ```typescript
230
+ providers: {
231
+ ollama: {
232
+ host?: 'http://localhost:11434',
233
+ model?: 'llama3.2',
234
+ }
235
+ }
236
+ ```
237
+
238
+ ### OpenAI-compatible (Kimi, Grok, any endpoint)
239
+
240
+ ```typescript
241
+ providers: {
242
+ kimi: { apiKey: process.env.KIMI_API_KEY!, model: 'moonshot-v1-8k' },
243
+ grok: { apiKey: process.env.GROK_API_KEY!, model: 'grok-3' },
244
+ // Any OpenAI-compatible endpoint
245
+ vllm: { apiKey: 'local', baseUrl: 'http://localhost:8080/v1', model: 'my-model' },
246
+ }
247
+ ```
100
248
 
101
249
  ---
102
250
 
103
- ## Skills
251
+ ## Built-in agents
104
252
 
105
- Skills inject domain knowledge into the agent's context when triggered by keywords.
253
+ Ten specialist agents are bundled. Orchestration routes tasks automatically; you can also select explicitly.
106
254
 
107
- ```ts
108
- // Built-in global skills (always available)
109
- // conventional-commits, code-review, tdd, adr, security-checklist
255
+ | Agent ID | Specialty |
256
+ |----------|-----------|
257
+ | `general` | General-purpose — default starting point |
258
+ | `architect` | System design, ADRs, architecture decisions |
259
+ | `backend-agent` | APIs, server logic, databases |
260
+ | `frontend-agent` | React, CSS, accessibility, UX |
261
+ | `devops-agent` | CI/CD, Docker, Kubernetes, infra |
262
+ | `database-agent` | SQL, indexes, migrations, query tuning |
263
+ | `security-reviewer` | Security audits, OWASP, threat modeling |
264
+ | `qa-engineer` | Test strategy, edge cases, QA reviews |
265
+ | `documentation-agent` | Docs, READMEs, API docs, changelogs |
266
+ | `refactoring-agent` | Code cleanup, technical debt, design patterns |
110
267
 
111
- // Built-in language packs (activated by detected stack)
112
- // node-pack, python-pack, go-pack, java-pack, kotlin-pack
268
+ ### Selecting an agent
113
269
 
114
- // Install external skill packs
115
- // /skills install https://github.com/my-org/my-skills
270
+ ```typescript
271
+ await engine.run('Audit src/ for SQL injection risks', { agentId: 'security-reviewer' });
116
272
  ```
117
273
 
274
+ ### Adding custom agents
275
+
276
+ Create `~/.bk-agent/agents/my-agent.json`:
277
+
278
+ ```json
279
+ {
280
+ "id": "my-agent",
281
+ "name": "My Custom Agent",
282
+ "systemPrompt": "You are specialized in ...",
283
+ "tools": ["read_file", "run_command"],
284
+ "provider": "anthropic"
285
+ }
286
+ ```
287
+
288
+ Loaded automatically — no code changes needed.
289
+
118
290
  ---
119
291
 
120
- ## createCodingEngine options
292
+ ## Built-in tools
293
+
294
+ All agents have access to these tools via `CODING_TOOLS`:
295
+
296
+ | Tool | Description |
297
+ |------|-------------|
298
+ | `read_file` | Read a file by path |
299
+ | `write_file` | Create or overwrite a file |
300
+ | `edit_file` | Apply a targeted patch to a file |
301
+ | `list_directory` | List files in a directory |
302
+ | `run_command` | Execute a shell command |
303
+ | `search_files` | Recursive content search |
304
+ | `save_context` | Write to `session.md` (persisted notes) |
305
+ | `save_learning` | Append to `lecciones-aprendidas.md` |
306
+ | `save_audit` | Write a structured audit entry |
307
+ | `get_latest_audit` | Read the latest audit |
308
+ | `list_audits` | List audit entries |
309
+ | `save_user_preference` | Persist user preferences |
310
+ | `update_session` | Update the in-progress session note |
311
+
312
+ ---
313
+
314
+ ## Skill packs
315
+
316
+ Built-in packs activate based on detected project stack:
121
317
 
122
- ```ts
123
- createCodingEngine({
124
- providers, // { [id]: { apiKey, model?, baseUrl? } }
125
- defaultProvider, // provider ID to use by default
126
- workingDir, // project root — all file tools are scoped here
127
- appName, // used for ~/.{appName}/ data directory
128
- transport, // CallbackTransport | StdoutTransport
129
- maxIterations?, // default: 50
130
- iterationMode?, // 'interactive' | 'auto' | 'step-by-step'
131
- mcpServers?, // MCP server configs for external tool providers
132
- orchestration?, // enable orchestration pipeline (risk scoring, gates)
133
- })
318
+ | Pack | Activates for |
319
+ |------|---------------|
320
+ | `GLOBAL_BUILTIN_SKILLS` | All projects |
321
+ | `NODE_PACK_SKILLS` | Node.js / TypeScript (`package.json`) |
322
+ | `GO_PACK_SKILLS` | Go (`go.mod`) |
323
+ | `JAVA_PACK_SKILLS` | Java (`pom.xml`, `build.gradle`) |
324
+ | `KOTLIN_PACK_SKILLS` | Kotlin / Android |
325
+ | `PYTHON_PACK_SKILLS` | Python (`requirements.txt`, `pyproject.toml`) |
326
+
327
+ ---
328
+
329
+ ## Orchestration pipeline
330
+
331
+ When `orchestration: true`, an intelligent routing layer runs before each LLM call:
332
+
333
+ ```
334
+ Input
335
+ → Intent Detection (feature? bug? refactor? question?)
336
+ → Domain Detection (backend? frontend? security? ops?)
337
+ → Risk Scoring (reads only? writes files? runs commands?)
338
+ → Policy Engine (enforce domain-level rules)
339
+ → Agent Selection (best agent for detected domain + risk)
340
+ → LLM Call
341
+ → QA Review (auto-review code-heavy responses)
342
+ ```
343
+
344
+ ### Custom orchestration
345
+
346
+ ```typescript
347
+ orchestration: {
348
+ capabilityMatrix: {
349
+ 'my-specialist': {
350
+ owns: ['payments', 'billing'],
351
+ skills: ['typescript', 'stripe'],
352
+ baseWeight: 0.95,
353
+ },
354
+ },
355
+ customRules: [
356
+ {
357
+ if: { domain: 'security' },
358
+ then: { mustInclude: ['security-reviewer'] },
359
+ },
360
+ ],
361
+ enableQA: true,
362
+ noQA: false,
363
+ onQAReview: (review) => logger.info('[QA]', review),
364
+ }
134
365
  ```
135
366
 
136
367
  ---
137
368
 
138
- ## Per-agent model overrides
369
+ ## Reflection engine
139
370
 
140
- Each agent can run on a different model. Set `model` (and optionally `provider`) on the agent profile, or use environment variables so the split is configurable without code changes:
371
+ Observes failures across runs, promotes recurring patterns into policy rules:
141
372
 
142
- ```ts
143
- // createCodingEngine wires LLM_MODEL_SMART → reasoning agents, LLM_MODEL_FAST → execution agents
373
+ ```typescript
374
+ orchestration: {
375
+ reflection: true,
376
+ // After each sprint:
377
+ // 1. Failures logged to FailureCatalog
378
+ // 2. Patterns with ≥3 occurrences promoted to PolicyRules
379
+ // 3. lecciones-aprendidas.md updated
380
+ }
144
381
  ```
145
382
 
146
- | Env var | Default | Purpose |
147
- |---|---|---|
148
- | `LLM_MODEL` | `gpt-4o` | Base model — used by all agents with no explicit override |
149
- | `LLM_MODEL_FAST` | `LLM_MODEL` | Execution agents (coder, backend, frontend, qa, infra, data) |
150
- | `LLM_MODEL_SMART` | `LLM_MODEL` | Reasoning agents (general, architecture, security, project-manager) |
383
+ ---
151
384
 
152
- Example `.env` for DeepSeek:
385
+ ## MCP server integration
386
+
387
+ ```typescript
388
+ mcpServers: [
389
+ {
390
+ name: 'code-intelligence',
391
+ command: 'bk-mcp', // @backendkit-labs/mcp-server
392
+ args: [],
393
+ env: { BK_APP_NAME: 'bk-agent', BK_CWD: process.cwd() },
394
+ },
395
+ {
396
+ name: 'github',
397
+ command: 'npx',
398
+ args: ['-y', '@modelcontextprotocol/server-github'],
399
+ env: { GITHUB_TOKEN: process.env.GITHUB_TOKEN! },
400
+ },
401
+ ],
402
+ subAgentContextMessages: 20,
403
+ ```
153
404
 
154
- ```env
155
- LLM_API_KEY=sk-...
156
- LLM_BASE_URL=https://api.deepseek.com/v1
157
- LLM_MODEL=deepseek-chat
158
- LLM_MODEL_FAST=deepseek-chat
159
- LLM_MODEL_SMART=deepseek-reasoner
405
+ ---
406
+
407
+ ## Multi-agent examples
408
+
409
+ ### Feature implementation
410
+
411
+ ```typescript
412
+ await engine.run(`
413
+ Implement JWT authentication middleware for Express:
414
+ - Validate Bearer token in Authorization header
415
+ - Attach decoded user to req.user
416
+ - Return 401 with clear error messages
417
+ - Include unit tests with valid/expired/malformed token cases
418
+ `);
419
+ // architect plans → backend-agent implements → qa-engineer writes tests
160
420
  ```
161
421
 
162
- Example `.env` mixing providers (OpenAI fast + Anthropic smart):
422
+ ### Security audit
163
423
 
164
- ```env
165
- LLM_API_KEY=sk-openai-...
166
- LLM_BASE_URL=https://api.openai.com/v1
167
- LLM_MODEL=gpt-4o-mini
168
- LLM_MODEL_FAST=gpt-4o-mini
169
- # Smart agents need a separate provider registered in engine.ts
424
+ ```typescript
425
+ await engine.run(`
426
+ Audit all routes in src/routes/ for:
427
+ 1. Missing auth middleware
428
+ 2. SQL injection vulnerabilities
429
+ 3. Exposed sensitive data
430
+ Output a prioritized fix list.
431
+ `, { agentId: 'security-reviewer' });
170
432
  ```
171
433
 
172
- For completely different LLM backends per agent, register multiple providers and set `provider` on the `AgentProfile`. See `@backendkit-labs/agent-core` docs for the multi-provider setup.
434
+ ### Database migration
173
435
 
174
- ---
436
+ ```typescript
437
+ await engine.run(`
438
+ Write a zero-downtime migration: add NOT NULL column
439
+ 'last_login_at TIMESTAMP DEFAULT NOW()' to the users table (50M rows).
440
+ Include rollback script and backfill strategy.
441
+ `, { agentId: 'database-agent' });
442
+ ```
175
443
 
176
- ## License
444
+ ### Full stack refactor
177
445
 
178
- MIT © [BackendKit Labs](https://github.com/BackendKit-labs)
446
+ ```typescript
447
+ await engine.run(`
448
+ Refactor auth from session cookies to JWT.
449
+ Update both Express middleware and React login flow.
450
+ Keep backward compatibility for 2 more sprints.
451
+ `);
452
+ // backend-agent + frontend-agent + security-reviewer
453
+ ```
454
+
455
+ ---
456
+
457
+ ## Config file
458
+
459
+ `~/.bk-agent/config.json`:
460
+
461
+ ```json
462
+ {
463
+ "defaultProvider": "deepseek",
464
+ "providers": {
465
+ "deepseek": { "apiKey": "sk-xxxx", "model": "deepseek-chat" },
466
+ "anthropic": { "apiKey": "sk-ant-xxxx", "model": "claude-sonnet-4-6" },
467
+ "ollama": { "host": "http://localhost:11434", "model": "llama3.2" }
468
+ },
469
+ "mcpServers": [
470
+ {
471
+ "name": "github",
472
+ "command": "npx",
473
+ "args": ["-y", "@modelcontextprotocol/server-github"],
474
+ "env": { "GITHUB_TOKEN": "ghp_xxxx" }
475
+ }
476
+ ]
477
+ }
478
+ ```
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@backendkit-labs/agent-coding",
3
- "version": "0.19.2",
3
+ "version": "0.19.3",
4
4
  "description": "Coding agent profiles and tools for @backendkit-labs/agent-core",
5
5
  "main": "dist/index.js",
6
6
  "types": "dist/index.d.ts",