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> — 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 -- lua-tools/json-encode.lua function main(args) local value = args[1]