Krebs

A self-hosted AI gateway with a general-purpose agent at its core.

Not a coding tool — any task requiring AI assistance works.

---

Features

Context Compression Layers

Token Usage
    │
    ├── Perception ── Session History RAG ──── Inject relevant past sessions (BM25)
    │
    ├── 50% ─── Memory ───────────── Consolidate to MEMORY.md
    │
    ├── 70% ─── Micro Compact ───── Prune old tool outputs
    │
    ├── 75% ─── Context Collapse ── Summarize dialogue to projection
    │
    └── 83.5% ─ Auto Compact ────── Built into pi-coding-agent

Perception Phase ── Goal Constraint ───────── Monitor drift, inject correction

Sandbox (Write Command Isolation)

Write commands execute in a WASM sandbox via wasmtime + coreutils.wasm:

• Sandbox restricts file system access to cwd via --dir flag
• Read commands bypass sandbox for full shell capabilities
• Only simple commands supported (no pipes, redirects, or chaining)

Memory (Two-Phase Consolidation)

50% Token ──► LLM Summarize ──► MEMORY.md (append)

Session Start ──► Read MEMORY.md ──► Inject into systemPrompt

• Write Phase: At 50% token usage, LLM generates a summary of recent messages → appends to MEMORY.md
• Read Phase: On session start, MEMORY.md content is injected into agent’s system prompt
• Rollback: Sessions can invalidate prior consolidations via session entries

Session History RAG (Perception Phase)

User Message → before_agent_start → BM25 retrieval → Inject relevant past sessions

• Timing: before_agent_start hook (perception phase), once per session
• Retrieval: BM25 algorithm matches current query with historical session firstQuestions
• Injection: Top-2 relevant sessions (1000 chars each) formatted and injected into systemPrompt
• Protection: Skip if context >80% full, skip on intent (restart/clear), 3s timeout

Goal Constraint (Perception Phase)

Context Event → Token threshold detection → Drift detection → Inject correction

• Goal Extraction: At 25%/40%/55% token thresholds, LLM extracts core goal from conversation history
• Drift Detection: BM25 hybrid scoring (keyword weight 0.6 + semantic weight 0.4) compares current dialogue with goal
• Correction Injection: On drift detection, prepend [GOAL CONSTRAINT] correction message to message list
• Cooldown: 3-turn cooldown after correction to prevent over-intervention

Self-Verification (Post-Response Phase)

Agent Response → Verification Check → Correction injection (if drift detected)

• Timing: After each agent response (skips first 2 turns)
• Verification: LLM checks if response aligns with original task/goal
• Correction: If misalignment detected, injects [SELF-VERIFICATION] correction message
• Retry: Up to 5 retries before accepting potentially drifted response

Subagent (Fleet / Task Management)

The agent can launch autonomous sub-agents, manage tasks, and schedule recurring jobs:

Main Agent ──► Agent(task)     ──► Subagent (runs independently)
            ──► TaskExecute    ──► Task (queued, run by subagent)
            ──► Schedule       ──► Recurring job (cron or interval)
            ──► FleetView      ──► See all running agents

Tools available to the agent:

429 Retry Handling

API rate limits (HTTP 429) are handled with automatic exponential backoff:

429 → retry 1 (2s) → retry 2 (4s) → retry 3 (8s) → fail

• Max attempts: 3 (configurable)
• Delays: Exponential [2000, 4000, 8000] ms
• During retry: New prompts are rejected with rate_limited event
• User abort: Send { type: "abort_retry" } to cancel in-progress retry
• pi-agent retry events: auto_retry_start/end are forwarded to frontend, but control flow uses custom ws.data.retryState for accurate prompt preservation

---

Quick Start

bun install
export DEEPSEEK_API_KEY=your_key
bun run server/index.ts
open http://localhost:3333

---

Environment

---

Architecture

                        Browser              HTTP Client             Script
                              │                   │                    │
                         ┌────▼────┐       ┌────▼────┐        ┌────▼────┐
                         │   Web   │       │   HTTP  │        │   WS    │
                         │   UI    │       │   API   │        │  Client │
                         └────┬────┘       └────┬────┘        └────┬────┘
                              │                 │                 │
                              └─────────────────┼─────────────────┘
                                                │
                              ┌─────────────────▼─────────────────┐
                              │          Krebs Gateway              │
                              │                                    │
                              │  ws-router        HTTP routes       │
                              │  ├── PromptHandler /api/messages   │
                              │  ├── SwitchSession /api/sessions   │
                              │  └── (inlined)     /api/auth       │
                              └─────────────────┬─────────────────┘
                                                │
                              ┌─────────────────▼─────────────────┐
                              │              Agent                   │
                              │                                       │
                              │  session-service                      │
                              │    creates / manages runtime          │
                              │                                       │
                              │  .pi/extensions/                       │
                              │    ├── context/ (Compression)         │
                              │    ├── memory/ (Consolidation 50%)   │
                              │    ├── memory-context/ (Injection)   │
                              │    ├── session-history-rag/ (RAG)    │
                              │    ├── goal-constraint/ (Drift)       │
                              │    ├── self-verification/ (Verify)    │
                              │    └── subagent/ (Fleet/Tasks)         │
                              │                                       │
                              │  server/services/                     │
                              │    ├── compact/                      │
                              │    ├── memory/                       │
                              │    ├── session-history/ (BM25+tools) │
                              │    ├── goal-constraint/ (Engine)    │
                              │    ├── self-verification/ (LLM)     │
                              │    └── subagent/ (Fleet/Tasks)       │
                              │                                       │
                              │  server/sandbox/                       │
                              │    └── wasmtime + coreutils.wasm     │
                              │                                       │
                              │  event-subscription                   │
                              │    forwards events → WebSocket        │
                              │                                       │
                              │  tools/  +  lua-tools/  +  skills/  │
                              │  bash      9 Lua scripts     7 skills│
                              └───────────────────────────────────────┘
                                                │
                              ┌─────────────────▼───────────────────┐
                              │        SessionManager                 │
                              │   persists sessions → ./sessions/    │
                              └─────────────────────────────────────┘

                              ┌─────────────────────────────────────┐
                              │     db/sessions_meta (SQLite)         │
                              │  sessionId → sessionFile mapping     │
                              └─────────────────────────────────────┘

---

Context Compression Layers

When token usage reaches thresholds, compression triggers automatically:

---

HTTP API

Requires Authorization: Bearer — token printed to console on first start and saved to .env.

Send a message

curl -X POST http://localhost:3333/api/messages \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"message": "Help me plan a trip to Japan"}'

Returns {sessionId, response, generatedContent}.

Resume a session

curl -X POST http://localhost:3333/api/messages \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"message": "Continue", "sessionId": "session_xxx"}'

Session management

# List all sessions
curl http://localhost:3333/api/sessions/list -H "Authorization: Bearer $TOKEN"

# Get session details
curl http://localhost:3333/api/sessions/:sessionId -H "Authorization: Bearer $TOKEN"

# Delete a session
curl -X DELETE http://localhost:3333/api/sessions/:sessionId -H "Authorization: Bearer $TOKEN"

---

WebSocket API

const ws = new WebSocket("ws://localhost:3333/ws");
ws.onopen = () => ws.send(JSON.stringify({ type: "auth" }));

Receive events:

Send messages

ws.send(JSON.stringify({ type: "prompt", message: "Hello" }));
ws.send(JSON.stringify({ type: "stop" }));
ws.send(JSON.stringify({ type: "abort_retry" }));        // abort in-progress retry
ws.send(JSON.stringify({ type: "switch_session", sessionId: "..." }));

---

Web UI

Open http://localhost:3333/. Connects to /ws, authenticates automatically.

• Real-time token streaming
• Markdown rendering
• Session history sidebar
• Stop / restart generation

---

Lua Tools

Drop a Lua script into lua-tools/, restart the server. Agent can call it by name.

-- lua-tools/json-encode.lua
function main(args)
  local value = args[1]
  return cjson.encode(value)
end

Agent calls it as lua_exec("json-encode", { value }).

---

Skills

Skills are SKILL.md files the agent reads when relevant. All 7 are listed in skills/index.ts.

---

Project Structure

Krebs/
├── server/
│   ├── index.ts              # Bun.serve() bootstrap
│   ├── session-service.ts   # Runtime factory + lifecycle
│   ├── event-subscription.ts # Events → WebSocket
│   ├── ws-router.ts         # WS message routing
│   ├── handlers/            # PromptHandler, SwitchSessionHandler (Auth/Stop inlined in ws-router)
│   ├── sandbox/             # WASM sandbox for write commands
│   │   ├── executor.ts      # wasmtime + coreutils runner
│   │   └── tools/bash.ts    # Sandbox bash tool
│   └── services/
│       ├── compact/          # Context compression
│       │   ├── microCompact.ts
│       │   └── contextCollapse.ts
│       ├── memory/           # Memory consolidation
│       │   ├── engine.ts     # LLM summary generation
│       │   ├── storage.ts    # MEMORY.md read/write
│       │   ├── llm.ts       # LLM calls
│       │   └── types.ts     # Constants & types
│       ├── session-history/  # Session History RAG
│       │   ├── bm25.ts      # BM25 algorithm + tokenizer
│       │   ├── indexer.ts   # Index build + cache
│       │   ├── storage.ts   # Content extraction
│       │   └── types.ts     # Type definitions
│       └── goal-constraint/  # Goal constraint
│           ├── engine.ts     # Drift detection engine
│           ├── llm.ts       # LLM goal extraction
│           ├── semantic.ts   # Hybrid scoring
│           ├── storage.ts   # Persistence
│           └── types.ts     # Constants & types
│       ├── self-verification/  # Post-response LLM verification
│       │   ├── llm.ts       # Verification LLM calls
│       │   └── types.ts     # Result types
│       └── subagent/        # Fleet / task management
│           ├── agent-manager.ts  # Subagent lifecycle
│           ├── scheduler.ts   # Cron/interval job scheduler
│           ├── fleet-view.ts  # Running agents overview
│           ├── custom-agents.ts  # Load from .pi/agents
│           └── types.ts     # Shared types
│
├── .pi/extensions/          # pi-coding-agent hooks
│   ├── context/             # Compression hooks
│   ├── memory/              # Memory consolidation (50% trigger)
│   ├── memory-context/      # Memory injection (session start)
│   ├── session-history-rag/ # Session History RAG (before_agent_start)
│   ├── goal-constraint/    # Goal constraint (context event)
│   ├── self-verification/  # Self-verification (post-response)
│   └── subagent/           # Subagent fleet management
│
├── lib/                     # Shared utilities
│
├── tools/                   # Tool system
│   └── lua-*.ts
│
├── lua-tools/               # 9 Lua scripts
│
├── skills/                  # 7 skills
│
├── frontend/                # React 19 app
│
├── db/                      # SQLite
│
├── wasm/                    # wasmtime + coreutils.wasm
│
└── prompts/                # System prompt

---

Tech Stack

Bun · TypeScript · React 19 · bun:sqlite · WebSocket · Wasmoon (Lua 5.4)