spb/khaelor Public
KHAELOR — a terminal-native autonomous engineering agent powered by Anthropic.
TypeScript 82.9%
HTML 14.9%
CSS 1.1%
JavaScript 0.7%
1<!doctype html>2<!--3KHAELOR4File: website/public/docs/events.html5Description: Docs — 40 durable event types, the JSONL contract, byte-exact replay, pairing safety, and why auditability falls out for free.6Author: Simon-Pierre Boucher7Contact: contact@spboucher.ai8-->9<html lang="en">10<head>11<meta charset="utf-8">12<meta name="viewport" content="width=device-width, initial-scale=1">13<title>The event model — KHAELOR docs</title>14<meta name="description" content="40 durable event types, the JSONL contract, byte-exact replay, pairing safety, and why auditability falls out for free.">15<link rel="stylesheet" href="/styles.css">16<script>17(function(){try{var t=localStorage.getItem("khaelor-theme");if(!t&&window.matchMedia&&window.matchMedia("(prefers-color-scheme: light)").matches)t="light";if(t==="light")document.documentElement.setAttribute("data-theme","light");}catch(e){}})();18</script>19<script defer src="/site.js"></script>20</head>21<body>2223<header class="site-header"><div class="inner">24 <a class="wordmark" href="/"><span class="glyph">❯</span><span class="g-ember">KHAELOR</span></a>25 <nav>26 <a href="/docs/getting-started.html">Docs</a>27 <a href="/#install">Install</a>28 <button id="theme-toggle" type="button" aria-label="Toggle color theme">light</button>29 </nav>30</div></header>3132<main class="page"><div class="docs-layout">3334<aside class="sidebar">35 <div class="group"><div class="group-title">Start</div>36 <a href="/docs/getting-started.html">Getting started</a>37 <a href="/docs/cookbook.html">Cookbook</a>38 </div>39 <div class="group"><div class="group-title">Using KHAELOR</div>40 <a href="/docs/usage.html">The TUI</a>41 <a href="/docs/commands.html">Commands & keyboard</a>42 <a href="/docs/tools.html">Tools</a>43 <a href="/docs/sessions.html">Sessions</a>44 </div>45 <div class="group"><div class="group-title">Autonomy</div>46 <a href="/docs/phases.html">Phase gates</a>47 <a href="/docs/verification.html">Verification</a>48 <a href="/docs/worktrees.html">Parallel worktrees</a>49 <a href="/docs/daemon.html">The daemon</a>50 </div>51 <div class="group"><div class="group-title">Intelligence</div>52 <a href="/docs/repograph.html">Semantic index</a>53 <a href="/docs/memory.html">Project memory</a>54 <a href="/docs/context.html">Context engine</a>55 <a href="/docs/fork-replay.html">Fork · replay · sdiff</a>56 </div>57 <div class="group"><div class="group-title">Control</div>58 <a href="/docs/permissions.html">Permissions</a>59 <a href="/docs/configuration.html">Configuration</a>60 <a href="/docs/cli.html">CLI reference</a>61 </div>62 <div class="group"><div class="group-title">Internals</div>63 <a href="/docs/architecture.html">Architecture</a>64 <a href="/docs/events.html">The event model</a>65 <a href="/docs/theming.html">Theming & terminal</a>66 </div>67 <div class="group"><div class="group-title">Help</div>68 <a href="/docs/faq.html">FAQ & troubleshooting</a>69 </div>70</aside>7172<article class="content">7374<h1>The event model</h1>75<p class="lead">The append-only event log is the source of truth. Everything else — the76conversation, the costs, the diffs, the phases — is a fold over it.</p>7778<h2 id="envelope">The envelope<a class="anchor" href="#envelope">#</a></h2>79<pre><code>{"v":1,"id":"01J8…","sessionId":"01J8…","seq":42,"ts":1765400000000,80 "type":"tool.completed","payload":{…}}</code></pre>81<ul>82 <li><code>seq</code> is gapless and assigned at append time; one complete line per write, never interleaved.</li>83 <li>A torn final line (crash mid-write) is quarantined to a <code>.torn</code> file and truncated84 away on open — corruption anywhere else refuses to resume rather than silently repairing.</li>85 <li><code>tool.requested</code> inputs are canonicalized (sorted keys) so a replayed history86 reproduces identical bytes on every rebuild.</li>87</ul>8889<h2 id="families">The 40 durable types, by family<a class="anchor" href="#families">#</a></h2>90<table>91 <tr><th>Family</th><th>Types</th></tr>92 <tr><td>Session</td><td class="wrap">started · resumed · renamed · model-changed · git.baseline-recorded</td></tr>93 <tr><td>User</td><td class="wrap">message-created · steering-queued · steering-injected · interrupted</td></tr>94 <tr><td>Model</td><td class="wrap">request-started · text/thinking-block-completed · response-completed · request-failed</td></tr>95 <tr><td>Tools</td><td class="wrap">requested · approved · started · completed · failed · cancelled</td></tr>96 <tr><td>Permissions</td><td class="wrap">requested · granted · denied</td></tr>97 <tr><td>Files & processes</td><td class="wrap">file.read · file.modified · process.started · process.exited</td></tr>98 <tr><td>Context</td><td class="wrap">pruned · compacted</td></tr>99 <tr><td>Completion</td><td class="wrap">verification-requested · task.completed · task.failed</td></tr>100 <tr><td>Phases (v2)</td><td class="wrap">phase.entered · phase.artifact · phase.approved · phase.rejected</td></tr>101 <tr><td>Verify / memory / subtasks (v2)</td><td class="wrap">verify.result · memory.written · subtask.created · subtask.completed</td></tr>102</table>103<p>Six ephemeral types (streaming deltas, live tool output) flow on the bus but are never104persisted — the log records what settled, not the typing noise.</p>105106<h2 id="pairing">Pairing safety<a class="anchor" href="#pairing">#</a></h2>107<p>Every <code>tool_use</code> must meet its <code>tool_result</code> — across interruptions,108crashes, and compactions. Resume closes dangling calls with synthetic cancellations; a compaction109cut is validated so it can never orphan a pair. This single invariant is why the API replay of any110KHAELOR session is always well-formed.</p>111112<h2 id="folds">Everything is a fold<a class="anchor" href="#folds">#</a></h2>113<table>114 <tr><th>Question</th><th>Fold</th></tr>115 <tr><td>What does the model see?</td><td class="wrap"><code>buildConversation(events)</code> — deterministic, byte-stable, prune/compaction re-applied from their recorded payloads.</td></tr>116 <tr><td>What did this cost?</td><td class="wrap"><code>buildUsageTotals(events)</code> — sums only <code>response-completed</code> usage. Nothing else may contribute.</td></tr>117 <tr><td>What changed on disk?</td><td class="wrap"><code>buildFileChangeSet(events)</code> — baseline + file.modified, attribution-aware.</td></tr>118 <tr><td>What phase am I in?</td><td class="wrap"><code>foldPhaseState(events)</code>.</td></tr>119 <tr><td>What should happen next?</td><td class="wrap"><code>foldTurnState(events)</code> → <code>deriveNext</code> — the kernel itself.</td></tr>120</table>121122<h2 id="audit">Why audit falls out for free<a class="anchor" href="#audit">#</a></h2>123<p>Because state is never anywhere else, <em>explaining</em> any behavior — including a daemon124run at 3 AM — is reading a file. <code>/fork</code> is a file-prefix copy. <code>/replay</code> is125re-driving the user turns. <code>/sdiff</code> is two folds side by side. None of these are126features bolted on; they are corollaries of the event model.</p>127128<div class="pager">129 <div><span class="label">Previous</span><a href="/docs/architecture.html">← Architecture</a></div>130 <div class="next"><span class="label">Next</span><a href="/docs/theming.html">Theming & terminal →</a></div>131</div>132133</article>134</div></main>135136<footer class="site-footer"><div class="inner">137 <span>KHAELOR — Simon-Pierre Boucher · <a href="mailto:contact@spboucher.ai">contact@spboucher.ai</a></span>138 <span>Anthropic-powered · terminal-native by design</span>139</div></footer>140141</body>142</html>143