@backendkit-labs/agent-coding 0.27.3 → 0.28.0
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.
- package/README.md +496 -480
- package/dist/__tests__/workspace-trust.test.d.ts +2 -0
- package/dist/__tests__/workspace-trust.test.d.ts.map +1 -0
- package/dist/__tests__/workspace-trust.test.js +171 -0
- package/dist/__tests__/workspace-trust.test.js.map +1 -0
- package/dist/agents/AgentLoader.d.ts +6 -0
- package/dist/agents/AgentLoader.d.ts.map +1 -1
- package/dist/agents/AgentLoader.js +13 -8
- package/dist/agents/AgentLoader.js.map +1 -1
- package/dist/index.d.ts +7 -0
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +10 -2
- package/dist/index.js.map +1 -1
- package/package.json +2 -2
package/README.md
CHANGED
|
@@ -1,480 +1,496 @@
|
|
|
1
|
-
# @backendkit-labs/agent-coding
|
|
2
|
-
|
|
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
|
-
[](https://www.npmjs.com/package/@backendkit-labs/agent-coding)
|
|
6
|
-
|
|
7
|
-
> **Status: `stable`** — Maintained and production-ready. No new features during the pilot phase.
|
|
8
|
-
|
|
9
|
-
## Table of contents
|
|
10
|
-
|
|
11
|
-
- [Installation](#installation)
|
|
12
|
-
- [Quick start](#quick-start)
|
|
13
|
-
- [createCodingEngine](#createcodingengine)
|
|
14
|
-
- [createCodingEngineFromConfig](#createcodingenginefromconfig)
|
|
15
|
-
- [Providers](#providers)
|
|
16
|
-
- [Built-in agents](#built-in-agents)
|
|
17
|
-
- [Built-in tools](#built-in-tools)
|
|
18
|
-
- [Skill packs](#skill-packs)
|
|
19
|
-
- [Orchestration pipeline](#orchestration-pipeline)
|
|
20
|
-
- [Reflection engine](#reflection-engine)
|
|
21
|
-
- [MCP server integration](#mcp-server-integration)
|
|
22
|
-
- [Multi-agent examples](#multi-agent-examples)
|
|
23
|
-
- [Config file](#config-file)
|
|
24
|
-
|
|
25
|
-
---
|
|
26
|
-
|
|
27
|
-
## Installation
|
|
28
|
-
|
|
29
|
-
```bash
|
|
30
|
-
npm install @backendkit-labs/agent-coding
|
|
31
|
-
```
|
|
32
|
-
|
|
33
|
-
All provider adapters are bundled — no separate packages needed.
|
|
34
|
-
|
|
35
|
-
---
|
|
36
|
-
|
|
37
|
-
## Quick start
|
|
38
|
-
|
|
39
|
-
```typescript
|
|
40
|
-
import { createCodingEngine } from '@backendkit-labs/agent-coding';
|
|
41
|
-
|
|
42
|
-
const engine = createCodingEngine({
|
|
43
|
-
providers: { deepseek: { apiKey: process.env.DEEPSEEK_API_KEY! } },
|
|
44
|
-
defaultProvider: 'deepseek',
|
|
45
|
-
});
|
|
46
|
-
|
|
47
|
-
await engine.run('List all TypeScript files in src/ and tell me which ones have no tests');
|
|
48
|
-
```
|
|
49
|
-
|
|
50
|
-
That single call gives you: 10 specialized agents, filesystem tools (read/write/edit/search), persistent project memory, skill loading, and stack auto-detection.
|
|
51
|
-
|
|
52
|
-
---
|
|
53
|
-
|
|
54
|
-
## createCodingEngine
|
|
55
|
-
|
|
56
|
-
The primary factory. Returns a fully configured `AgentEngine`.
|
|
57
|
-
|
|
58
|
-
### Options reference
|
|
59
|
-
|
|
60
|
-
```typescript
|
|
61
|
-
interface CodingEngineOptions {
|
|
62
|
-
// Required
|
|
63
|
-
providers: ProvidersConfig;
|
|
64
|
-
defaultProvider: string;
|
|
65
|
-
|
|
66
|
-
// Agents and engine
|
|
67
|
-
defaultAgent?: string; // default: 'general'
|
|
68
|
-
workingDir?: string; // default: process.cwd()
|
|
69
|
-
maxIterations?: number; // default: 100
|
|
70
|
-
maxParallelAgents?: number; // default: 6
|
|
71
|
-
|
|
72
|
-
// I/O
|
|
73
|
-
transport?: Transport; // default: StdoutTransport
|
|
74
|
-
|
|
75
|
-
// App identity
|
|
76
|
-
appName?: string; // default: 'bk-agent' — used for ~/.{appName}/
|
|
77
|
-
|
|
78
|
-
// Persistence
|
|
79
|
-
disablePersistence?: boolean; // skip ProjectStore (useful for testing)
|
|
80
|
-
|
|
81
|
-
// MCP servers
|
|
82
|
-
mcpServers?: MCPServerConfig[];
|
|
83
|
-
|
|
84
|
-
// Context sharing
|
|
85
|
-
subAgentContextMessages?: number; // messages visible to sub-agents (recommend 10-20)
|
|
86
|
-
|
|
87
|
-
// Iteration control
|
|
88
|
-
onToolApproval?: (toolName, agentId, argsPreview) => Promise<ToolApprovalDecision>;
|
|
89
|
-
onIterationLimit?: (stats: IterationStats) => Promise<boolean>;
|
|
90
|
-
onStep?: (stats: IterationStats) => Promise<boolean>;
|
|
91
|
-
|
|
92
|
-
// Orchestration
|
|
93
|
-
orchestration?: boolean | OrchestrationOptions;
|
|
94
|
-
}
|
|
95
|
-
```
|
|
96
|
-
|
|
97
|
-
### Minimal setup
|
|
98
|
-
|
|
99
|
-
```typescript
|
|
100
|
-
const engine = createCodingEngine({
|
|
101
|
-
providers: { deepseek: { apiKey: 'sk-...' } },
|
|
102
|
-
defaultProvider: 'deepseek',
|
|
103
|
-
});
|
|
104
|
-
```
|
|
105
|
-
|
|
106
|
-
### Multiple providers
|
|
107
|
-
|
|
108
|
-
```typescript
|
|
109
|
-
const engine = createCodingEngine({
|
|
110
|
-
providers: {
|
|
111
|
-
deepseek: { apiKey: process.env.DEEPSEEK_API_KEY! },
|
|
112
|
-
anthropic: { apiKey: process.env.ANTHROPIC_API_KEY!, model: 'claude-opus-4-8' },
|
|
113
|
-
ollama: { host: 'http://localhost:11434', model: 'llama3.2' },
|
|
114
|
-
},
|
|
115
|
-
defaultProvider: 'deepseek',
|
|
116
|
-
// Each agent profile can specify a provider override
|
|
117
|
-
});
|
|
118
|
-
```
|
|
119
|
-
|
|
120
|
-
### With full orchestration
|
|
121
|
-
|
|
122
|
-
```typescript
|
|
123
|
-
const engine = createCodingEngine({
|
|
124
|
-
providers: { deepseek: { apiKey: '...' } },
|
|
125
|
-
defaultProvider: 'deepseek',
|
|
126
|
-
orchestration: true,
|
|
127
|
-
// Enables:
|
|
128
|
-
// intent detection → domain detection → risk scoring
|
|
129
|
-
// policy engine → agent routing → QA auto-review → reflection
|
|
130
|
-
});
|
|
131
|
-
```
|
|
132
|
-
|
|
133
|
-
### With MCP servers
|
|
134
|
-
|
|
135
|
-
```typescript
|
|
136
|
-
const engine = createCodingEngine({
|
|
137
|
-
providers: { openai: { apiKey: '...' } },
|
|
138
|
-
defaultProvider: 'openai',
|
|
139
|
-
mcpServers: [
|
|
140
|
-
{ name: 'github', command: 'npx', args: ['-y', '@modelcontextprotocol/server-github'], env: { GITHUB_TOKEN: '...' } },
|
|
141
|
-
{ name: 'postgres', command: 'npx', args: ['-y', '@modelcontextprotocol/server-postgres'], env: { DATABASE_URL: '...' } },
|
|
142
|
-
],
|
|
143
|
-
subAgentContextMessages: 15,
|
|
144
|
-
});
|
|
145
|
-
```
|
|
146
|
-
|
|
147
|
-
### With manual tool approval
|
|
148
|
-
|
|
149
|
-
```typescript
|
|
150
|
-
const engine = createCodingEngine({
|
|
151
|
-
providers: { deepseek: { apiKey: '...' } },
|
|
152
|
-
defaultProvider: 'deepseek',
|
|
153
|
-
onToolApproval: async (toolName, agentId, argsPreview) => {
|
|
154
|
-
const write = ['write_file', 'edit_file', 'run_command'];
|
|
155
|
-
if (!write.includes(toolName)) return 'approve';
|
|
156
|
-
console.log(`\n⚠ [${agentId}] ${toolName}:\n${argsPreview}\n`);
|
|
157
|
-
const a = await prompt('Approve? (y/n/all): ');
|
|
158
|
-
if (a === 'y') return 'approve';
|
|
159
|
-
if (a === 'all') return 'approve_all';
|
|
160
|
-
return 'reject';
|
|
161
|
-
},
|
|
162
|
-
});
|
|
163
|
-
```
|
|
164
|
-
|
|
165
|
-
---
|
|
166
|
-
|
|
167
|
-
## createCodingEngineFromConfig
|
|
168
|
-
|
|
169
|
-
Reads credentials from `~/.{appName}/config.json`. No code changes needed to switch providers:
|
|
170
|
-
|
|
171
|
-
```typescript
|
|
172
|
-
import { createCodingEngineFromConfig } from '@backendkit-labs/agent-coding';
|
|
173
|
-
|
|
174
|
-
const engine = createCodingEngineFromConfig();
|
|
175
|
-
|
|
176
|
-
// With overrides
|
|
177
|
-
const engine = createCodingEngineFromConfig({
|
|
178
|
-
workingDir: '/my-project',
|
|
179
|
-
orchestration: true,
|
|
180
|
-
});
|
|
181
|
-
```
|
|
182
|
-
|
|
183
|
-
---
|
|
184
|
-
|
|
185
|
-
## Providers
|
|
186
|
-
|
|
187
|
-
### DeepSeek
|
|
188
|
-
|
|
189
|
-
```typescript
|
|
190
|
-
providers: {
|
|
191
|
-
deepseek: {
|
|
192
|
-
apiKey: process.env.DEEPSEEK_API_KEY!,
|
|
193
|
-
model?: 'deepseek-chat', // default
|
|
194
|
-
maxTokens?: 8192,
|
|
195
|
-
temperature?: 0.7,
|
|
196
|
-
}
|
|
197
|
-
}
|
|
198
|
-
```
|
|
199
|
-
|
|
200
|
-
### OpenAI
|
|
201
|
-
|
|
202
|
-
```typescript
|
|
203
|
-
providers: {
|
|
204
|
-
openai: {
|
|
205
|
-
apiKey: process.env.OPENAI_API_KEY!,
|
|
206
|
-
model?: 'gpt-4o',
|
|
207
|
-
baseUrl?: 'https://api.openai.com/v1',
|
|
208
|
-
}
|
|
209
|
-
}
|
|
210
|
-
```
|
|
211
|
-
|
|
212
|
-
### Anthropic (Claude)
|
|
213
|
-
|
|
214
|
-
```typescript
|
|
215
|
-
providers: {
|
|
216
|
-
anthropic: {
|
|
217
|
-
apiKey: process.env.ANTHROPIC_API_KEY!,
|
|
218
|
-
model?: 'claude-sonnet-4-6', // default
|
|
219
|
-
}
|
|
220
|
-
}
|
|
221
|
-
```
|
|
222
|
-
|
|
223
|
-
### Ollama (local — no API key)
|
|
224
|
-
|
|
225
|
-
```bash
|
|
226
|
-
# Prerequisites
|
|
227
|
-
ollama serve
|
|
228
|
-
ollama pull llama3.2
|
|
229
|
-
```
|
|
230
|
-
|
|
231
|
-
```typescript
|
|
232
|
-
providers: {
|
|
233
|
-
ollama: {
|
|
234
|
-
host?: 'http://localhost:11434',
|
|
235
|
-
model?: 'llama3.2',
|
|
236
|
-
}
|
|
237
|
-
}
|
|
238
|
-
```
|
|
239
|
-
|
|
240
|
-
### OpenAI-compatible (Kimi, Grok, any endpoint)
|
|
241
|
-
|
|
242
|
-
```typescript
|
|
243
|
-
providers: {
|
|
244
|
-
kimi: { apiKey: process.env.KIMI_API_KEY!, model: 'moonshot-v1-8k' },
|
|
245
|
-
grok: { apiKey: process.env.GROK_API_KEY!, model: 'grok-3' },
|
|
246
|
-
// Any OpenAI-compatible endpoint
|
|
247
|
-
vllm: { apiKey: 'local', baseUrl: 'http://localhost:8080/v1', model: 'my-model' },
|
|
248
|
-
}
|
|
249
|
-
```
|
|
250
|
-
|
|
251
|
-
---
|
|
252
|
-
|
|
253
|
-
## Built-in agents
|
|
254
|
-
|
|
255
|
-
Ten specialist agents are bundled. Orchestration routes tasks automatically; you can also select explicitly.
|
|
256
|
-
|
|
257
|
-
| Agent ID | Specialty |
|
|
258
|
-
|----------|-----------|
|
|
259
|
-
| `general` | General-purpose — default starting point |
|
|
260
|
-
| `architect` | System design, ADRs, architecture decisions |
|
|
261
|
-
| `backend-agent` | APIs, server logic, databases |
|
|
262
|
-
| `frontend-agent` | React, CSS, accessibility, UX |
|
|
263
|
-
| `devops-agent` | CI/CD, Docker, Kubernetes, infra |
|
|
264
|
-
| `database-agent` | SQL, indexes, migrations, query tuning |
|
|
265
|
-
| `security-reviewer` | Security audits, OWASP, threat modeling |
|
|
266
|
-
| `qa-engineer` | Test strategy, edge cases, QA reviews |
|
|
267
|
-
| `documentation-agent` | Docs, READMEs, API docs, changelogs |
|
|
268
|
-
| `refactoring-agent` | Code cleanup, technical debt, design patterns |
|
|
269
|
-
|
|
270
|
-
### Selecting an agent
|
|
271
|
-
|
|
272
|
-
```typescript
|
|
273
|
-
await engine.run('Audit src/ for SQL injection risks', { agentId: 'security-reviewer' });
|
|
274
|
-
```
|
|
275
|
-
|
|
276
|
-
### Adding custom agents
|
|
277
|
-
|
|
278
|
-
Create `~/.bk-agent/agents/my-agent.json`:
|
|
279
|
-
|
|
280
|
-
```json
|
|
281
|
-
{
|
|
282
|
-
"id": "my-agent",
|
|
283
|
-
"name": "My Custom Agent",
|
|
284
|
-
"systemPrompt": "You are specialized in ...",
|
|
285
|
-
"tools": ["read_file", "run_command"],
|
|
286
|
-
"provider": "anthropic"
|
|
287
|
-
}
|
|
288
|
-
```
|
|
289
|
-
|
|
290
|
-
Loaded automatically — no code changes needed.
|
|
291
|
-
|
|
292
|
-
|
|
293
|
-
|
|
294
|
-
|
|
295
|
-
|
|
296
|
-
|
|
297
|
-
|
|
298
|
-
|
|
299
|
-
|
|
300
|
-
|
|
301
|
-
|
|
302
|
-
|
|
303
|
-
|
|
304
|
-
|
|
305
|
-
|
|
306
|
-
|
|
307
|
-
|
|
308
|
-
|
|
309
|
-
|
|
310
|
-
|
|
311
|
-
|
|
312
|
-
|
|
313
|
-
|
|
314
|
-
|
|
315
|
-
|
|
316
|
-
|
|
317
|
-
|
|
318
|
-
|
|
319
|
-
|
|
320
|
-
|
|
|
321
|
-
|
|
322
|
-
| `
|
|
323
|
-
| `
|
|
324
|
-
| `
|
|
325
|
-
| `
|
|
326
|
-
| `
|
|
327
|
-
| `
|
|
328
|
-
|
|
329
|
-
|
|
330
|
-
|
|
331
|
-
|
|
332
|
-
|
|
333
|
-
|
|
334
|
-
|
|
335
|
-
|
|
336
|
-
|
|
337
|
-
|
|
338
|
-
|
|
339
|
-
|
|
340
|
-
|
|
341
|
-
|
|
342
|
-
|
|
343
|
-
|
|
344
|
-
|
|
345
|
-
|
|
346
|
-
|
|
347
|
-
|
|
348
|
-
|
|
349
|
-
orchestration:
|
|
350
|
-
|
|
351
|
-
|
|
352
|
-
|
|
353
|
-
|
|
354
|
-
|
|
355
|
-
|
|
356
|
-
|
|
357
|
-
|
|
358
|
-
|
|
359
|
-
|
|
360
|
-
|
|
361
|
-
|
|
362
|
-
|
|
363
|
-
|
|
364
|
-
|
|
365
|
-
|
|
366
|
-
|
|
367
|
-
|
|
368
|
-
|
|
369
|
-
|
|
370
|
-
|
|
371
|
-
|
|
372
|
-
|
|
373
|
-
|
|
374
|
-
|
|
375
|
-
|
|
376
|
-
|
|
377
|
-
|
|
378
|
-
|
|
379
|
-
|
|
380
|
-
|
|
381
|
-
|
|
382
|
-
}
|
|
383
|
-
```
|
|
384
|
-
|
|
385
|
-
---
|
|
386
|
-
|
|
387
|
-
##
|
|
388
|
-
|
|
389
|
-
|
|
390
|
-
|
|
391
|
-
|
|
392
|
-
|
|
393
|
-
|
|
394
|
-
|
|
395
|
-
|
|
396
|
-
|
|
397
|
-
|
|
398
|
-
|
|
399
|
-
|
|
400
|
-
|
|
401
|
-
|
|
402
|
-
|
|
403
|
-
|
|
404
|
-
|
|
405
|
-
```
|
|
406
|
-
|
|
407
|
-
|
|
408
|
-
|
|
409
|
-
|
|
410
|
-
|
|
411
|
-
|
|
412
|
-
|
|
413
|
-
|
|
414
|
-
|
|
415
|
-
|
|
416
|
-
|
|
417
|
-
|
|
418
|
-
|
|
419
|
-
|
|
420
|
-
|
|
421
|
-
|
|
422
|
-
|
|
423
|
-
|
|
424
|
-
|
|
425
|
-
|
|
426
|
-
|
|
427
|
-
|
|
428
|
-
|
|
429
|
-
|
|
430
|
-
|
|
431
|
-
|
|
432
|
-
|
|
433
|
-
|
|
434
|
-
|
|
435
|
-
|
|
436
|
-
|
|
437
|
-
|
|
438
|
-
```
|
|
439
|
-
|
|
440
|
-
|
|
441
|
-
|
|
442
|
-
|
|
443
|
-
|
|
444
|
-
|
|
445
|
-
|
|
446
|
-
|
|
447
|
-
|
|
448
|
-
|
|
449
|
-
|
|
450
|
-
|
|
451
|
-
|
|
452
|
-
|
|
453
|
-
|
|
454
|
-
|
|
455
|
-
|
|
456
|
-
|
|
457
|
-
|
|
458
|
-
|
|
459
|
-
|
|
460
|
-
|
|
461
|
-
|
|
462
|
-
|
|
463
|
-
|
|
464
|
-
|
|
465
|
-
|
|
466
|
-
|
|
467
|
-
|
|
468
|
-
|
|
469
|
-
|
|
470
|
-
|
|
471
|
-
|
|
472
|
-
|
|
473
|
-
|
|
474
|
-
|
|
475
|
-
|
|
476
|
-
|
|
477
|
-
|
|
478
|
-
|
|
479
|
-
|
|
480
|
-
|
|
1
|
+
# @backendkit-labs/agent-coding
|
|
2
|
+
|
|
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
|
+
[](https://www.npmjs.com/package/@backendkit-labs/agent-coding)
|
|
6
|
+
|
|
7
|
+
> **Status: `stable`** — Maintained and production-ready. No new features during the pilot phase.
|
|
8
|
+
|
|
9
|
+
## Table of contents
|
|
10
|
+
|
|
11
|
+
- [Installation](#installation)
|
|
12
|
+
- [Quick start](#quick-start)
|
|
13
|
+
- [createCodingEngine](#createcodingengine)
|
|
14
|
+
- [createCodingEngineFromConfig](#createcodingenginefromconfig)
|
|
15
|
+
- [Providers](#providers)
|
|
16
|
+
- [Built-in agents](#built-in-agents)
|
|
17
|
+
- [Built-in tools](#built-in-tools)
|
|
18
|
+
- [Skill packs](#skill-packs)
|
|
19
|
+
- [Orchestration pipeline](#orchestration-pipeline)
|
|
20
|
+
- [Reflection engine](#reflection-engine)
|
|
21
|
+
- [MCP server integration](#mcp-server-integration)
|
|
22
|
+
- [Multi-agent examples](#multi-agent-examples)
|
|
23
|
+
- [Config file](#config-file)
|
|
24
|
+
|
|
25
|
+
---
|
|
26
|
+
|
|
27
|
+
## Installation
|
|
28
|
+
|
|
29
|
+
```bash
|
|
30
|
+
npm install @backendkit-labs/agent-coding
|
|
31
|
+
```
|
|
32
|
+
|
|
33
|
+
All provider adapters are bundled — no separate packages needed.
|
|
34
|
+
|
|
35
|
+
---
|
|
36
|
+
|
|
37
|
+
## Quick start
|
|
38
|
+
|
|
39
|
+
```typescript
|
|
40
|
+
import { createCodingEngine } from '@backendkit-labs/agent-coding';
|
|
41
|
+
|
|
42
|
+
const engine = createCodingEngine({
|
|
43
|
+
providers: { deepseek: { apiKey: process.env.DEEPSEEK_API_KEY! } },
|
|
44
|
+
defaultProvider: 'deepseek',
|
|
45
|
+
});
|
|
46
|
+
|
|
47
|
+
await engine.run('List all TypeScript files in src/ and tell me which ones have no tests');
|
|
48
|
+
```
|
|
49
|
+
|
|
50
|
+
That single call gives you: 10 specialized agents, filesystem tools (read/write/edit/search), persistent project memory, skill loading, and stack auto-detection.
|
|
51
|
+
|
|
52
|
+
---
|
|
53
|
+
|
|
54
|
+
## createCodingEngine
|
|
55
|
+
|
|
56
|
+
The primary factory. Returns a fully configured `AgentEngine`.
|
|
57
|
+
|
|
58
|
+
### Options reference
|
|
59
|
+
|
|
60
|
+
```typescript
|
|
61
|
+
interface CodingEngineOptions {
|
|
62
|
+
// Required
|
|
63
|
+
providers: ProvidersConfig;
|
|
64
|
+
defaultProvider: string;
|
|
65
|
+
|
|
66
|
+
// Agents and engine
|
|
67
|
+
defaultAgent?: string; // default: 'general'
|
|
68
|
+
workingDir?: string; // default: process.cwd()
|
|
69
|
+
maxIterations?: number; // default: 100
|
|
70
|
+
maxParallelAgents?: number; // default: 6
|
|
71
|
+
|
|
72
|
+
// I/O
|
|
73
|
+
transport?: Transport; // default: StdoutTransport
|
|
74
|
+
|
|
75
|
+
// App identity
|
|
76
|
+
appName?: string; // default: 'bk-agent' — used for ~/.{appName}/
|
|
77
|
+
|
|
78
|
+
// Persistence
|
|
79
|
+
disablePersistence?: boolean; // skip ProjectStore (useful for testing)
|
|
80
|
+
|
|
81
|
+
// MCP servers
|
|
82
|
+
mcpServers?: MCPServerConfig[];
|
|
83
|
+
|
|
84
|
+
// Context sharing
|
|
85
|
+
subAgentContextMessages?: number; // messages visible to sub-agents (recommend 10-20)
|
|
86
|
+
|
|
87
|
+
// Iteration control
|
|
88
|
+
onToolApproval?: (toolName, agentId, argsPreview) => Promise<ToolApprovalDecision>;
|
|
89
|
+
onIterationLimit?: (stats: IterationStats) => Promise<boolean>;
|
|
90
|
+
onStep?: (stats: IterationStats) => Promise<boolean>;
|
|
91
|
+
|
|
92
|
+
// Orchestration
|
|
93
|
+
orchestration?: boolean | OrchestrationOptions;
|
|
94
|
+
}
|
|
95
|
+
```
|
|
96
|
+
|
|
97
|
+
### Minimal setup
|
|
98
|
+
|
|
99
|
+
```typescript
|
|
100
|
+
const engine = createCodingEngine({
|
|
101
|
+
providers: { deepseek: { apiKey: 'sk-...' } },
|
|
102
|
+
defaultProvider: 'deepseek',
|
|
103
|
+
});
|
|
104
|
+
```
|
|
105
|
+
|
|
106
|
+
### Multiple providers
|
|
107
|
+
|
|
108
|
+
```typescript
|
|
109
|
+
const engine = createCodingEngine({
|
|
110
|
+
providers: {
|
|
111
|
+
deepseek: { apiKey: process.env.DEEPSEEK_API_KEY! },
|
|
112
|
+
anthropic: { apiKey: process.env.ANTHROPIC_API_KEY!, model: 'claude-opus-4-8' },
|
|
113
|
+
ollama: { host: 'http://localhost:11434', model: 'llama3.2' },
|
|
114
|
+
},
|
|
115
|
+
defaultProvider: 'deepseek',
|
|
116
|
+
// Each agent profile can specify a provider override
|
|
117
|
+
});
|
|
118
|
+
```
|
|
119
|
+
|
|
120
|
+
### With full orchestration
|
|
121
|
+
|
|
122
|
+
```typescript
|
|
123
|
+
const engine = createCodingEngine({
|
|
124
|
+
providers: { deepseek: { apiKey: '...' } },
|
|
125
|
+
defaultProvider: 'deepseek',
|
|
126
|
+
orchestration: true,
|
|
127
|
+
// Enables:
|
|
128
|
+
// intent detection → domain detection → risk scoring
|
|
129
|
+
// policy engine → agent routing → QA auto-review → reflection
|
|
130
|
+
});
|
|
131
|
+
```
|
|
132
|
+
|
|
133
|
+
### With MCP servers
|
|
134
|
+
|
|
135
|
+
```typescript
|
|
136
|
+
const engine = createCodingEngine({
|
|
137
|
+
providers: { openai: { apiKey: '...' } },
|
|
138
|
+
defaultProvider: 'openai',
|
|
139
|
+
mcpServers: [
|
|
140
|
+
{ name: 'github', command: 'npx', args: ['-y', '@modelcontextprotocol/server-github'], env: { GITHUB_TOKEN: '...' } },
|
|
141
|
+
{ name: 'postgres', command: 'npx', args: ['-y', '@modelcontextprotocol/server-postgres'], env: { DATABASE_URL: '...' } },
|
|
142
|
+
],
|
|
143
|
+
subAgentContextMessages: 15,
|
|
144
|
+
});
|
|
145
|
+
```
|
|
146
|
+
|
|
147
|
+
### With manual tool approval
|
|
148
|
+
|
|
149
|
+
```typescript
|
|
150
|
+
const engine = createCodingEngine({
|
|
151
|
+
providers: { deepseek: { apiKey: '...' } },
|
|
152
|
+
defaultProvider: 'deepseek',
|
|
153
|
+
onToolApproval: async (toolName, agentId, argsPreview) => {
|
|
154
|
+
const write = ['write_file', 'edit_file', 'run_command'];
|
|
155
|
+
if (!write.includes(toolName)) return 'approve';
|
|
156
|
+
console.log(`\n⚠ [${agentId}] ${toolName}:\n${argsPreview}\n`);
|
|
157
|
+
const a = await prompt('Approve? (y/n/all): ');
|
|
158
|
+
if (a === 'y') return 'approve';
|
|
159
|
+
if (a === 'all') return 'approve_all';
|
|
160
|
+
return 'reject';
|
|
161
|
+
},
|
|
162
|
+
});
|
|
163
|
+
```
|
|
164
|
+
|
|
165
|
+
---
|
|
166
|
+
|
|
167
|
+
## createCodingEngineFromConfig
|
|
168
|
+
|
|
169
|
+
Reads credentials from `~/.{appName}/config.json`. No code changes needed to switch providers:
|
|
170
|
+
|
|
171
|
+
```typescript
|
|
172
|
+
import { createCodingEngineFromConfig } from '@backendkit-labs/agent-coding';
|
|
173
|
+
|
|
174
|
+
const engine = createCodingEngineFromConfig();
|
|
175
|
+
|
|
176
|
+
// With overrides
|
|
177
|
+
const engine = createCodingEngineFromConfig({
|
|
178
|
+
workingDir: '/my-project',
|
|
179
|
+
orchestration: true,
|
|
180
|
+
});
|
|
181
|
+
```
|
|
182
|
+
|
|
183
|
+
---
|
|
184
|
+
|
|
185
|
+
## Providers
|
|
186
|
+
|
|
187
|
+
### DeepSeek
|
|
188
|
+
|
|
189
|
+
```typescript
|
|
190
|
+
providers: {
|
|
191
|
+
deepseek: {
|
|
192
|
+
apiKey: process.env.DEEPSEEK_API_KEY!,
|
|
193
|
+
model?: 'deepseek-chat', // default
|
|
194
|
+
maxTokens?: 8192,
|
|
195
|
+
temperature?: 0.7,
|
|
196
|
+
}
|
|
197
|
+
}
|
|
198
|
+
```
|
|
199
|
+
|
|
200
|
+
### OpenAI
|
|
201
|
+
|
|
202
|
+
```typescript
|
|
203
|
+
providers: {
|
|
204
|
+
openai: {
|
|
205
|
+
apiKey: process.env.OPENAI_API_KEY!,
|
|
206
|
+
model?: 'gpt-4o',
|
|
207
|
+
baseUrl?: 'https://api.openai.com/v1',
|
|
208
|
+
}
|
|
209
|
+
}
|
|
210
|
+
```
|
|
211
|
+
|
|
212
|
+
### Anthropic (Claude)
|
|
213
|
+
|
|
214
|
+
```typescript
|
|
215
|
+
providers: {
|
|
216
|
+
anthropic: {
|
|
217
|
+
apiKey: process.env.ANTHROPIC_API_KEY!,
|
|
218
|
+
model?: 'claude-sonnet-4-6', // default
|
|
219
|
+
}
|
|
220
|
+
}
|
|
221
|
+
```
|
|
222
|
+
|
|
223
|
+
### Ollama (local — no API key)
|
|
224
|
+
|
|
225
|
+
```bash
|
|
226
|
+
# Prerequisites
|
|
227
|
+
ollama serve
|
|
228
|
+
ollama pull llama3.2
|
|
229
|
+
```
|
|
230
|
+
|
|
231
|
+
```typescript
|
|
232
|
+
providers: {
|
|
233
|
+
ollama: {
|
|
234
|
+
host?: 'http://localhost:11434',
|
|
235
|
+
model?: 'llama3.2',
|
|
236
|
+
}
|
|
237
|
+
}
|
|
238
|
+
```
|
|
239
|
+
|
|
240
|
+
### OpenAI-compatible (Kimi, Grok, any endpoint)
|
|
241
|
+
|
|
242
|
+
```typescript
|
|
243
|
+
providers: {
|
|
244
|
+
kimi: { apiKey: process.env.KIMI_API_KEY!, model: 'moonshot-v1-8k' },
|
|
245
|
+
grok: { apiKey: process.env.GROK_API_KEY!, model: 'grok-3' },
|
|
246
|
+
// Any OpenAI-compatible endpoint
|
|
247
|
+
vllm: { apiKey: 'local', baseUrl: 'http://localhost:8080/v1', model: 'my-model' },
|
|
248
|
+
}
|
|
249
|
+
```
|
|
250
|
+
|
|
251
|
+
---
|
|
252
|
+
|
|
253
|
+
## Built-in agents
|
|
254
|
+
|
|
255
|
+
Ten specialist agents are bundled. Orchestration routes tasks automatically; you can also select explicitly.
|
|
256
|
+
|
|
257
|
+
| Agent ID | Specialty |
|
|
258
|
+
|----------|-----------|
|
|
259
|
+
| `general` | General-purpose — default starting point |
|
|
260
|
+
| `architect` | System design, ADRs, architecture decisions |
|
|
261
|
+
| `backend-agent` | APIs, server logic, databases |
|
|
262
|
+
| `frontend-agent` | React, CSS, accessibility, UX |
|
|
263
|
+
| `devops-agent` | CI/CD, Docker, Kubernetes, infra |
|
|
264
|
+
| `database-agent` | SQL, indexes, migrations, query tuning |
|
|
265
|
+
| `security-reviewer` | Security audits, OWASP, threat modeling |
|
|
266
|
+
| `qa-engineer` | Test strategy, edge cases, QA reviews |
|
|
267
|
+
| `documentation-agent` | Docs, READMEs, API docs, changelogs |
|
|
268
|
+
| `refactoring-agent` | Code cleanup, technical debt, design patterns |
|
|
269
|
+
|
|
270
|
+
### Selecting an agent
|
|
271
|
+
|
|
272
|
+
```typescript
|
|
273
|
+
await engine.run('Audit src/ for SQL injection risks', { agentId: 'security-reviewer' });
|
|
274
|
+
```
|
|
275
|
+
|
|
276
|
+
### Adding custom agents
|
|
277
|
+
|
|
278
|
+
Create `~/.bk-agent/agents/my-agent.json`:
|
|
279
|
+
|
|
280
|
+
```json
|
|
281
|
+
{
|
|
282
|
+
"id": "my-agent",
|
|
283
|
+
"name": "My Custom Agent",
|
|
284
|
+
"systemPrompt": "You are specialized in ...",
|
|
285
|
+
"tools": ["read_file", "run_command"],
|
|
286
|
+
"provider": "anthropic"
|
|
287
|
+
}
|
|
288
|
+
```
|
|
289
|
+
|
|
290
|
+
Loaded automatically — no code changes needed.
|
|
291
|
+
|
|
292
|
+
### Project agents and skills need a trusted project
|
|
293
|
+
|
|
294
|
+
Agents in `{project}/.bk-agent/agents/` and skills in `{project}/.bk-agent/skills/` are the **repository's** content, not yours: a cloned repo could ship an agent that replaces the built-in orchestrator with its own prompt and tools. So they load only for a project you trusted. Your own agents and skills under `~/.bk-agent/` always load.
|
|
295
|
+
|
|
296
|
+
```text
|
|
297
|
+
/trust # is this project trusted, and what would its project layer load
|
|
298
|
+
/trust add # trust it (records the real path in ~/.bk-agent/trusted-projects.json)
|
|
299
|
+
/trust remove # stop trusting it
|
|
300
|
+
/trust list
|
|
301
|
+
```
|
|
302
|
+
|
|
303
|
+
- Trust is by **exact path**: trusting `~/code` does not trust a repository cloned inside it.
|
|
304
|
+
- For a project that is not trusted, the engine emits a warning naming what was left out. Skills load right after `/trust add`; agents the next time the agent starts.
|
|
305
|
+
- `BK_TRUST_PROJECT=1` trusts every path (CI, containers). A host that decides by itself can pass `trustedProject: true | false` to `createCodingEngine`.
|
|
306
|
+
- A missing or damaged trust file means nobody is trusted.
|
|
307
|
+
|
|
308
|
+
---
|
|
309
|
+
|
|
310
|
+
## Built-in tools
|
|
311
|
+
|
|
312
|
+
All agents have access to these tools via `CODING_TOOLS`:
|
|
313
|
+
|
|
314
|
+
| Tool | Description |
|
|
315
|
+
|------|-------------|
|
|
316
|
+
| `read_file` | Read a file by path |
|
|
317
|
+
| `write_file` | Create or overwrite a file |
|
|
318
|
+
| `edit_file` | Apply a targeted patch to a file |
|
|
319
|
+
| `list_directory` | List files in a directory |
|
|
320
|
+
| `run_command` | Execute a shell command |
|
|
321
|
+
| `search_files` | Recursive content search |
|
|
322
|
+
| `save_context` | Write to `session.md` (persisted notes) |
|
|
323
|
+
| `save_learning` | Append to `lecciones-aprendidas.md` |
|
|
324
|
+
| `save_audit` | Write a structured audit entry |
|
|
325
|
+
| `get_latest_audit` | Read the latest audit |
|
|
326
|
+
| `list_audits` | List audit entries |
|
|
327
|
+
| `save_user_preference` | Persist user preferences |
|
|
328
|
+
| `update_session` | Update the in-progress session note |
|
|
329
|
+
|
|
330
|
+
---
|
|
331
|
+
|
|
332
|
+
## Skill packs
|
|
333
|
+
|
|
334
|
+
Built-in packs activate based on detected project stack:
|
|
335
|
+
|
|
336
|
+
| Pack | Activates for |
|
|
337
|
+
|------|---------------|
|
|
338
|
+
| `GLOBAL_BUILTIN_SKILLS` | All projects |
|
|
339
|
+
| `NODE_PACK_SKILLS` | Node.js / TypeScript (`package.json`) |
|
|
340
|
+
| `GO_PACK_SKILLS` | Go (`go.mod`) |
|
|
341
|
+
| `JAVA_PACK_SKILLS` | Java (`pom.xml`, `build.gradle`) |
|
|
342
|
+
| `KOTLIN_PACK_SKILLS` | Kotlin / Android |
|
|
343
|
+
| `PYTHON_PACK_SKILLS` | Python (`requirements.txt`, `pyproject.toml`) |
|
|
344
|
+
|
|
345
|
+
---
|
|
346
|
+
|
|
347
|
+
## Orchestration pipeline
|
|
348
|
+
|
|
349
|
+
When `orchestration: true`, an intelligent routing layer runs before each LLM call:
|
|
350
|
+
|
|
351
|
+
```
|
|
352
|
+
Input
|
|
353
|
+
→ Intent Detection (feature? bug? refactor? question?)
|
|
354
|
+
→ Domain Detection (backend? frontend? security? ops?)
|
|
355
|
+
→ Risk Scoring (reads only? writes files? runs commands?)
|
|
356
|
+
→ Policy Engine (enforce domain-level rules)
|
|
357
|
+
→ Agent Selection (best agent for detected domain + risk)
|
|
358
|
+
→ LLM Call
|
|
359
|
+
→ QA Review (auto-review code-heavy responses)
|
|
360
|
+
```
|
|
361
|
+
|
|
362
|
+
### Custom orchestration
|
|
363
|
+
|
|
364
|
+
```typescript
|
|
365
|
+
orchestration: {
|
|
366
|
+
capabilityMatrix: {
|
|
367
|
+
'my-specialist': {
|
|
368
|
+
owns: ['payments', 'billing'],
|
|
369
|
+
skills: ['typescript', 'stripe'],
|
|
370
|
+
baseWeight: 0.95,
|
|
371
|
+
},
|
|
372
|
+
},
|
|
373
|
+
customRules: [
|
|
374
|
+
{
|
|
375
|
+
if: { domain: 'security' },
|
|
376
|
+
then: { mustInclude: ['security-reviewer'] },
|
|
377
|
+
},
|
|
378
|
+
],
|
|
379
|
+
enableQA: true,
|
|
380
|
+
noQA: false,
|
|
381
|
+
onQAReview: (review) => logger.info('[QA]', review),
|
|
382
|
+
}
|
|
383
|
+
```
|
|
384
|
+
|
|
385
|
+
---
|
|
386
|
+
|
|
387
|
+
## Reflection engine
|
|
388
|
+
|
|
389
|
+
Observes failures across runs, promotes recurring patterns into policy rules:
|
|
390
|
+
|
|
391
|
+
```typescript
|
|
392
|
+
orchestration: {
|
|
393
|
+
reflection: true,
|
|
394
|
+
// After each sprint:
|
|
395
|
+
// 1. Failures logged to FailureCatalog
|
|
396
|
+
// 2. Patterns with ≥3 occurrences promoted to PolicyRules
|
|
397
|
+
// 3. lecciones-aprendidas.md updated
|
|
398
|
+
}
|
|
399
|
+
```
|
|
400
|
+
|
|
401
|
+
---
|
|
402
|
+
|
|
403
|
+
## MCP server integration
|
|
404
|
+
|
|
405
|
+
```typescript
|
|
406
|
+
mcpServers: [
|
|
407
|
+
{
|
|
408
|
+
name: 'code-intelligence',
|
|
409
|
+
command: 'bk-mcp', // @backendkit-labs/mcp-server
|
|
410
|
+
args: [],
|
|
411
|
+
env: { BK_APP_NAME: 'bk-agent', BK_CWD: process.cwd() },
|
|
412
|
+
},
|
|
413
|
+
{
|
|
414
|
+
name: 'github',
|
|
415
|
+
command: 'npx',
|
|
416
|
+
args: ['-y', '@modelcontextprotocol/server-github'],
|
|
417
|
+
env: { GITHUB_TOKEN: process.env.GITHUB_TOKEN! },
|
|
418
|
+
},
|
|
419
|
+
],
|
|
420
|
+
subAgentContextMessages: 20,
|
|
421
|
+
```
|
|
422
|
+
|
|
423
|
+
---
|
|
424
|
+
|
|
425
|
+
## Multi-agent examples
|
|
426
|
+
|
|
427
|
+
### Feature implementation
|
|
428
|
+
|
|
429
|
+
```typescript
|
|
430
|
+
await engine.run(`
|
|
431
|
+
Implement JWT authentication middleware for Express:
|
|
432
|
+
- Validate Bearer token in Authorization header
|
|
433
|
+
- Attach decoded user to req.user
|
|
434
|
+
- Return 401 with clear error messages
|
|
435
|
+
- Include unit tests with valid/expired/malformed token cases
|
|
436
|
+
`);
|
|
437
|
+
// architect plans → backend-agent implements → qa-engineer writes tests
|
|
438
|
+
```
|
|
439
|
+
|
|
440
|
+
### Security audit
|
|
441
|
+
|
|
442
|
+
```typescript
|
|
443
|
+
await engine.run(`
|
|
444
|
+
Audit all routes in src/routes/ for:
|
|
445
|
+
1. Missing auth middleware
|
|
446
|
+
2. SQL injection vulnerabilities
|
|
447
|
+
3. Exposed sensitive data
|
|
448
|
+
Output a prioritized fix list.
|
|
449
|
+
`, { agentId: 'security-reviewer' });
|
|
450
|
+
```
|
|
451
|
+
|
|
452
|
+
### Database migration
|
|
453
|
+
|
|
454
|
+
```typescript
|
|
455
|
+
await engine.run(`
|
|
456
|
+
Write a zero-downtime migration: add NOT NULL column
|
|
457
|
+
'last_login_at TIMESTAMP DEFAULT NOW()' to the users table (50M rows).
|
|
458
|
+
Include rollback script and backfill strategy.
|
|
459
|
+
`, { agentId: 'database-agent' });
|
|
460
|
+
```
|
|
461
|
+
|
|
462
|
+
### Full stack refactor
|
|
463
|
+
|
|
464
|
+
```typescript
|
|
465
|
+
await engine.run(`
|
|
466
|
+
Refactor auth from session cookies to JWT.
|
|
467
|
+
Update both Express middleware and React login flow.
|
|
468
|
+
Keep backward compatibility for 2 more sprints.
|
|
469
|
+
`);
|
|
470
|
+
// backend-agent + frontend-agent + security-reviewer
|
|
471
|
+
```
|
|
472
|
+
|
|
473
|
+
---
|
|
474
|
+
|
|
475
|
+
## Config file
|
|
476
|
+
|
|
477
|
+
`~/.bk-agent/config.json`:
|
|
478
|
+
|
|
479
|
+
```json
|
|
480
|
+
{
|
|
481
|
+
"defaultProvider": "deepseek",
|
|
482
|
+
"providers": {
|
|
483
|
+
"deepseek": { "apiKey": "sk-xxxx", "model": "deepseek-chat" },
|
|
484
|
+
"anthropic": { "apiKey": "sk-ant-xxxx", "model": "claude-sonnet-4-6" },
|
|
485
|
+
"ollama": { "host": "http://localhost:11434", "model": "llama3.2" }
|
|
486
|
+
},
|
|
487
|
+
"mcpServers": [
|
|
488
|
+
{
|
|
489
|
+
"name": "github",
|
|
490
|
+
"command": "npx",
|
|
491
|
+
"args": ["-y", "@modelcontextprotocol/server-github"],
|
|
492
|
+
"env": { "GITHUB_TOKEN": "ghp_xxxx" }
|
|
493
|
+
}
|
|
494
|
+
]
|
|
495
|
+
}
|
|
496
|
+
```
|