SPB Git

spb/khaelor Public

KHAELOR — a terminal-native autonomous engineering agent powered by Anthropic.

aiagentclianthropictypescript
TypeScript 82.9% HTML 14.9% CSS 1.1% JavaScript 0.7%
5.3 KB
View source Raw Blame History

# KHAELOR v2 — implementation notes (0.2.0)

The seven v2 work streams plus the "Terminal Cinema" TUI upgrade, as shipped. Every number below is enforced by npm run check (typecheck · eslint · vitest · header check).

# §1 Phase gates — src/phases/

  • Events: phase.entered / phase.artifact / phase.approved / phase.rejected (durable catalog, src/session/events.ts).
  • PhaseService sits AROUND the kernel: the Tool Runtime (src/agent/executor.ts) consults checkToolCall between capability mapping and permission evaluation; blocked calls fail with structured PHASE_GATE_BLOCKED repair prose.
  • Per-phase policy (src/phases/gate.ts): understand = read + read-only bash whitelist; design = + docs/design/*.md; implement = everything. .khaelor/MEMORY.md writable in every phase.
  • The model unlocks implement via the design tool (src/tools/design.ts).
  • Modes: --gate strict|auto|off, config gate.autoApprove.maxFiles (default 3). The doc's maxRiskLevel is not implemented — risks are free text; file count is the auto-approval criterion.
  • TUI: phase ribbon in the status bar, design panel (src/tui/components/design-panel.ts), strict-mode approval via the selector (Esc = reject; silence is never approval), /phase override.

# §4 Native verification — src/verify/

  • .khaelor/verify.json or auto-detection (package.json scripts / tsconfig / Cargo.toml / pyproject).
  • VerifyRunner runs checks in parallel (autofix checks last, serially) through the Workspace seam; each check is a durable verify.result with real exit codes and errors-first truncation.
  • Policy after-each-edit-batch (default) triggers in the executor after a successful write/edit batch. Failing results are folded into the conversation as user-visible input (the model repairs them) with a bounded loop: maxRepairLoops (default 3) failures per user turn, then honest stop.
  • before-final-answer maps onto the existing VerificationGate nudge flow; /verify runs on demand.

# §2 Fork / replay / sdiff — src/session/fork.ts, sdiff.ts, src/cli/replay.ts

  • <sessionId>.meta.json lineage (parent, forkPoint, replayOf).
  • /fork lists natural checkpoints (user turns, approved designs, compactions), copies the JSONL prefix (sessionIds rewritten, seq/payloads byte-preserved) and opens the fork.
  • /replay re-runs the user turns headless inside a throwaway worktree (--sandbox semantics built-in).
  • /sdiff folds two logs into turns/tool-calls/files/tokens/verify-failures/outcome.

# §5 Project memory — src/memory/, src/tools/remember.ts

  • .khaelor/MEMORY.md, entries anchored <!-- khaelor: session=… tool=… confidence=… date=… --> (the tool_use id is the event anchor). memory.written durable event.
  • Injected as a project-instruction tier at engine assembly; /memory lists with provenance; low-confidence entries surface as purge candidates.

# §3 RepoGraph — src/repograph/

  • Dependency-free heuristic extractor (TS/JS/Python): symbols, doc comments, imports. tree-sitter is the documented upgrade path — the service interface will not change.
  • Incremental by mtime, lazy debounced refresh, in-memory graph; symbols and refs (callers/callees/importers) tools; skeleton() produces signature-level file views for the context engine (wired for future compaction use).

# §6 Parallel worktrees — src/tasks/, src/cli/subtasks.ts

  • subtask.created / subtask.completed durable events with REAL git diff stats.
  • Children run a full headless engine in .khaelor/worktrees/<id> on branch khaelor/<id>: own JSONL (meta.parent → orchestrator), non-interactive permissions (asks deny), gates + verify on.
  • /spawn, /tasks, /merge (supervised --no-ff; conflicts abort cleanly).

# §7 Daemon — src/daemon/, bin khaelord

  • Scheduler (cron parser + heartbeat tick), event-sourced GoalStore (.khaelor/daemon/goals/<id>.json + .events.jsonl), BudgetGuard (hard daily/per-goal USD ceilings from a persisted ledger; costs only priced when pricing is configured — never invented), ApprovalQueue (persisted; suspended run costs zero), ChannelRouter (webhook + command adapters), control socket (status/goals/approvals/approve/deny/stop), khaelor TUI /goals view.
  • Goal runs = throwaway worktree + headless engine + gates + verify; escalation notify / draft-pr (branch left for review) / auto-merge-if-verified. LLM heartbeat triage is not implemented — the goal check command is the cheap tier; an injectable seam exists.

# TUI v2 — "Terminal Cinema"

  • Khaelis palette (obsidian + magma: ember #FF6B35 → glow #FFB86B, teal #2DD4BF) as the default dark theme; OKLCH gradient interpolation (src/tui/theme/gradient.ts), ember named gradient.
  • Cockpit status bar: phase ribbon + ▰▱ context gauge (≥110 cols) + cost; verify strip, design panel, braille sparkline widgets; splash (--splash, gradient sweep, skippable); MotionController (six sanctioned effects, tick-driven, motion-off aware); --doctor-tui.

# Website (www.khaelor.sh)

  • Full Khaelis redesign, v2 landing (cockpit demo, feature grid, daemon section, design-panel mock), new docs: phases.html, daemon.html; sessions/commands updated; installer artifact 0.2.0.