# KHY Agent 5-Step Implementation

This document maps your five-step method to the current KHY codebase and defines a practical rollout path.

## 0. Scope

Goal: build a production-capable agent runtime from existing components, not a greenfield rewrite.

Existing foundations already in repository:
- Context: `backend/src/services/contextRouter.js`, `contextCompressor.js`, `contextWindowGuard.js`, `agentContext.js`
- Loop: `backend/src/services/toolUseLoop.js`, `retryWithBackoff.js`, `backgroundTaskManager.js`, `flowsEngine.js`
- Skills: `backend/src/skills/index.js`, `backend/src/skills/skillLoader.js`, `backend/src/services/skillRegistry.js`
- Memory: `backend/src/memdir/`, `backend/src/services/projectMemoryService.js`, `sessionRecapService.js`
- Observability / Harness support: `backend/src/services/diagnosticEvents.js`, `traceAuditService.js`, `serviceRegistry.js`

New aggregation entrypoint:
- `backend/src/services/agenticHarnessService.js`

Integrated caller path (current):
- `backend/src/services/queryEngine.js` legacy loop now supports harness-first execution with automatic fallback.
- Env toggle: `KHY_QUERY_ENGINE_HARNESS=true|false` (default: `true`).
- `backend/src/cli/repl.js` tool loop path now supports harness-first execution with automatic fallback.
- `backend/src/cli/liteRepl.js` tool loop path now supports harness-first execution with automatic fallback.
- Shared REPL toggle: `KHY_REPL_HARNESS=true|false` (default: `true`).

---

## 1. Context Engineering -> Information Organization

### Objective
Keep context complete, structured, and cheap enough to fit model window limits.

### Design
- Use a three-tier context model:
  - Hot tier (session): current turn + short-lived cache
  - Warm tier (project): project memory and recent session traces
  - Cold tier (long-term): persistent memory files / external vector retriever
- Apply preemptive routing before model call:
  - `fits`
  - `compact_only`
  - `truncate_tool_results_only`
  - `compact_then_truncate`
- Build a context packet with:
  - route decision
  - token estimate
  - memory hints
  - active skill hints

### Code mapping
- Routing: `routeContextStrategy()` and `truncateToolResults()`
- Compression: `compress()` (best-effort)
- Packet assembly: `createAgenticHarness().buildContextPacket()`

### Acceptance criteria
- Context overflow no longer causes abrupt failure for normal tasks.
- Each run stores route + token estimate for traceability.

---

## 2. Agent Loop Engineering -> Continuous Task Execution

### Objective
Ensure long tasks continue and recover automatically from transient errors.

### Design
- Keep `toolUseLoop` as execution core.
- Add retry wrapper around loop call for transient outcomes:
  - `timeout`, `network`, `process`, `unknown`, `cancelled` (when no progress made)
- Bind run lifecycle to `backgroundTaskManager`:
  - prepare -> loop -> completed/failed

### Code mapping
- Loop core: `runToolUseLoop()`
- Retry: `retryWithBackoff()`
- Lifecycle state: `backgroundTaskManager.register/complete/fail`

### Acceptance criteria
- No single transient channel glitch should terminate a task immediately.
- Task state is always visible as running/completed/failed.

---

## 3. Skills Engineering -> Extensibility and Performance

### Objective
Activate the right capabilities for the current task without loading everything.

### Design
- Discover and prioritize skills by context:
  - project cwd
  - recent files
  - user intent tokens
- Return top-N active skill hints into the loop prompt.
- Keep plugin/skill execution path unchanged; optimize selection only.

### Code mapping
- Discovery: `skills.discoverAllSkills(cwd)`
- Activation: `skills.getActiveSkills({ cwd, recentFiles })`
- Ranking and hint output: `_collectSkillHints()` in `agenticHarnessService.js`

### Acceptance criteria
- Prompt includes relevant skills for non-trivial tasks.
- Skill selection cost stays bounded through caching.

---

## 4. Memory Engineering -> Context Window Breakthrough

### Objective
Support long-horizon continuity beyond current context window.

### Design
- Retrieve memory hints from:
  - text search (`memdir.searchMemories`)
  - optional vector retriever callback (`vectorRetriever`)
- Segment memory into short snippets for prompt injection.
- Persist run traces for future retrieval:
  - session metadata
  - route decision
  - tool-call progress

### Code mapping
- Retrieval and ranking: `_collectMemoryHints()`
- Persistence: `projectMemoryService.saveSessionTrace()`

### Acceptance criteria
- Long-running projects can resume with relevant historical hints.
- Memory hints are bounded and ranked, not dumped wholesale.

---

## 5. Harness Engineering -> Production Landing

### Objective
Turn the above into one reusable production runtime.

### Design
- Provide a unified run API:
  - `createAgenticHarness(options).run(request)`
- Require minimal inputs:
  - `userMessage`
  - `chat` function
- Expose structured run report:
  - duration
  - context route
  - token estimate
  - memory/skill hints
  - iterations and tool-call count

### Code mapping
- Runtime entrypoint: `backend/src/services/agenticHarnessService.js`

### Acceptance criteria
- CLI/REPL/Sub-agent flows can share the same harness interface.
- Each run emits a deterministic report for debugging and governance.

---

## Rollout Plan (Recommended)

1. Integrate harness into one entry flow first (REPL or queryEngine path).
2. Run `node scripts/check-agent-rules.js --changed` after each change set.
3. Add smoke tests for:
   - context route selection
   - transient retry path
   - memory + skill hint generation
4. Expand integration to sub-agents and web routes after initial stabilization.

---

## Summary Flow

Context Engineering -> packetized context + routing  
Agent Loop Engineering -> resilient execution + retry  
Skills Engineering -> dynamic capability activation  
Memory Engineering -> long-term recall + segmented hints  
Harness Engineering -> single runtime API + observability
