@kb-labs/agent-core 0.6.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 +83 -0
- package/dist/index.d.ts +2415 -0
- package/dist/index.js +12652 -0
- package/dist/index.js.map +1 -0
- package/package.json +58 -0
package/README.md
ADDED
|
@@ -0,0 +1,83 @@
|
|
|
1
|
+
# @kb-labs/agent-core
|
|
2
|
+
|
|
3
|
+
Main agent engine for KB Labs. Handles LLM orchestration, tool execution, budget management, quality gates, and task validation.
|
|
4
|
+
|
|
5
|
+
## Core Class
|
|
6
|
+
|
|
7
|
+
```typescript
|
|
8
|
+
import { Agent } from '@kb-labs/agent-core';
|
|
9
|
+
|
|
10
|
+
const agent = new Agent(config, toolRegistry);
|
|
11
|
+
const result = await agent.execute('Fix the authentication bug');
|
|
12
|
+
```
|
|
13
|
+
|
|
14
|
+
The `Agent` class runs an iterative LLM tool-calling loop: classify task, execute tools, check quality, validate completion.
|
|
15
|
+
|
|
16
|
+
## Module Map
|
|
17
|
+
|
|
18
|
+
The engine is decomposed into 15+ focused modules extracted from the main `Agent` class:
|
|
19
|
+
|
|
20
|
+
| Module | Purpose | Key Exports |
|
|
21
|
+
|--------|---------|-------------|
|
|
22
|
+
| `execution/` | State machine, ledger, checkpoint | `ExecutionStateMachine`, `ExecutionLedger` |
|
|
23
|
+
| `budget/` | Iteration limits, quality scoring, tier selection | `IterationBudget`, `QualityGate`, `TierSelector` |
|
|
24
|
+
| `prompt/` | System prompt construction | `SystemPromptBuilder` |
|
|
25
|
+
| `tool-input/` | Tool call normalization and guards | `ToolInputNormalizer` |
|
|
26
|
+
| `progress/` | Progress tracking | `ProgressTracker` |
|
|
27
|
+
| `search-signal/` | Search heuristics for discovery tasks | `SearchSignalTracker` |
|
|
28
|
+
| `analytics/` | Run KPIs, EMA baselines, regression detection | `RunMetricsEmitter` |
|
|
29
|
+
| `reflection/` | Self-evaluation between iterations | `ReflectionEngine` |
|
|
30
|
+
| `todo-sync/` | Todo-list lifecycle for phase tracking | `TodoSyncCoordinator` |
|
|
31
|
+
| `task-classifier/` | LLM-based intent + budget classification | `TaskClassifier` |
|
|
32
|
+
| `task-completion/` | Heuristic + LLM completion validation | `TaskCompletionEvaluator` |
|
|
33
|
+
| `context/` | Sliding window, summarization | `ContextFilter`, `SmartSummarizer` |
|
|
34
|
+
| `memory/` | Short-term, long-term, working memory | `MemoryManager` |
|
|
35
|
+
| `planning/` | Turn assembly, planning strategies | `TurnAssembler` |
|
|
36
|
+
| `modes/` | Execute, plan, edit, debug modes | `ModeRouter` |
|
|
37
|
+
| `events/` | Event emission for UI streaming | `EventEmitter` |
|
|
38
|
+
| `history/` | File change tracking integration | `FileChangeHistory` |
|
|
39
|
+
|
|
40
|
+
### Design Principles
|
|
41
|
+
|
|
42
|
+
- **Focused interfaces** — each module defines its own input types, zero dependency on Agent class
|
|
43
|
+
- **Callback injection** — LLM access, file I/O, tool execution provided via callbacks
|
|
44
|
+
- **Return data, not side effects** — modules return result objects; Agent applies side effects
|
|
45
|
+
- **Pure standalone functions** — exported for direct testing without class instantiation
|
|
46
|
+
|
|
47
|
+
## Execution Flow
|
|
48
|
+
|
|
49
|
+
```
|
|
50
|
+
classifyTask() → intent (action/discovery/analysis) + budget
|
|
51
|
+
↓
|
|
52
|
+
extractScope() → narrow working directory
|
|
53
|
+
↓
|
|
54
|
+
┌─ iteration loop ──────────────────────────────┐
|
|
55
|
+
│ buildPrompt() → system + context │
|
|
56
|
+
│ llm.chatWithTools() → tool calls │
|
|
57
|
+
│ executeTool() → results │
|
|
58
|
+
│ trackProgress() → phase transitions │
|
|
59
|
+
│ checkQualityGate() → score + tier decision │
|
|
60
|
+
│ reflect() → self-evaluation │
|
|
61
|
+
│ checkBudget() → continue or stop │
|
|
62
|
+
└────────────────────────────────────────────────┘
|
|
63
|
+
↓
|
|
64
|
+
validateCompletion() → success/failure + summary
|
|
65
|
+
↓
|
|
66
|
+
emitRunKpis() → analytics + regression detection
|
|
67
|
+
```
|
|
68
|
+
|
|
69
|
+
## Testing
|
|
70
|
+
|
|
71
|
+
```bash
|
|
72
|
+
pnpm test # 406 tests across 17 files
|
|
73
|
+
pnpm lint # 0 errors
|
|
74
|
+
pnpm type-check # strict mode
|
|
75
|
+
```
|
|
76
|
+
|
|
77
|
+
## Dependencies
|
|
78
|
+
|
|
79
|
+
- `@kb-labs/agent-contracts` — shared types
|
|
80
|
+
- `@kb-labs/agent-tools` — tool registry
|
|
81
|
+
- `@kb-labs/agent-history` — file change tracking
|
|
82
|
+
- `@kb-labs/agent-tracing` — trace writing
|
|
83
|
+
- `@kb-labs/sdk` — platform SDK (LLM interfaces, session management)
|