caxton 0.1.4

A secure WebAssembly runtime for multi-agent systems
Documentation
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
---
layout: default
---

<!-- Hero Section -->
<section class="hero">
    <div class="container">
        <div class="hero-content">
            <div class="hero-text">
                <h1 class="hero-title">
                    <span class="title-line">Build Multi-Agent Systems</span>
                    <span class="title-line gradient-text">That Don't Wake You Up</span>
                </h1>
                <p class="hero-subtitle">
                    WebAssembly isolation. Observable by design. Zero external dependencies.
                    Build distributed, resilient multi-agent systems with <span class="highlight">< 50μs overhead</span>.
                </p>
                <div class="hero-actions">
                    <a href="#getting-started" class="btn btn-primary">Get Started</a>
                    <a href="#architecture" class="btn btn-secondary">View Architecture</a>
                </div>
            </div>
            <div class="hero-visual">
                <div class="floating-card">
                    <img src="{{ '/assets/img/logo.svg' | relative_url }}" alt="Caxton Logo" class="hero-logo">
                </div>
            </div>
        </div>
    </div>
</section>

{{ content }}

<!-- Problem/Solution Section -->
<section id="problem-solution" class="problem-solution">
    <div class="container">
        <h2 class="section-title">Why Caxton Exists</h2>
        <div class="problem-grid">
            <div class="problem-card">
                <h3 class="problem-title">Current Pain Points</h3>
                <ul class="problem-list">
                    <li>Debugging distributed agent state is a nightmare</li>
                    <li>Agent crashes affect the entire system</li>
                    <li>No standard communication protocols</li>
                    <li>Network partitions break everything</li>
                    <li>Requires external databases for coordination</li>
                    <li>Observability is an afterthought</li>
                </ul>
            </div>
            <div class="solution-card">
                <h3 class="solution-title">How Caxton Solves Them</h3>
                <ul class="solution-list">
                    <li>Built-in distributed tracing for every message</li>
                    <li>WebAssembly isolation with zero blast radius</li>
                    <li>FIPA standard protocols out of the box</li>
                    <li>Graceful degradation during network partitions</li>
                    <li>No external dependencies - SWIM protocol built-in</li>
                    <li>OpenTelemetry from day one</li>
                </ul>
            </div>
        </div>
    </div>
</section>

<!-- Features Section -->
<section id="features" class="features">
    <div class="container">
        <h2 class="section-title">Core Features</h2>
        <div class="features-grid">
            <div class="feature-card">
                <div class="feature-icon">🛡️</div>
                <h3>WebAssembly Agent Isolation</h3>
                <p>Each agent runs in its own WebAssembly sandbox. When an agent crashes, the blast radius is zero. Like containers but 100x lighter.</p>
                <div class="feature-metrics">
                    <span class="metric">45μs spawn time</span>
                    <span class="metric">2MB baseline memory</span>
                </div>
            </div>
            <div class="feature-card">
                <div class="feature-icon">💬</div>
                <h3>FIPA Protocol Messaging</h3>
                <p>Industry-standard agent communication protocols at the application layer. Semantic messaging that works across cluster boundaries.</p>
                <div class="feature-protocols">
                    <span class="protocol">Contract Net</span>
                    <span class="protocol">Request/Reply</span>
                    <span class="protocol">Cross-Cluster</span>
                </div>
            </div>
            <div class="feature-card">
                <div class="feature-icon">🔍</div>
                <h3>Observable by Design</h3>
                <p>Built-in OpenTelemetry from day one. Every message traced, every decision logged, every metric captured.</p>
                <div class="feature-observability">
                    <span class="observable">Distributed Tracing</span>
                    <span class="observable">Structured Logs</span>
                    <span class="observable">Real Metrics</span>
                </div>
            </div>
            <div class="feature-card">
                <div class="feature-icon">🚀</div>
                <h3>Production Performance</h3>
                <p>Designed for real workloads, not demos. Microsecond latencies, predictable resource usage, graceful degradation.</p>
                <div class="feature-performance">
                    <span class="perf">12μs p50 latency</span>
                    <span class="perf">67μs p99 latency</span>
                    <span class="perf">10k agents/core</span>
                </div>
            </div>
            <div class="feature-card">
                <div class="feature-icon">🛠️</div>
                <h3>Debugging Tools</h3>
                <p>Purpose-built tools for 3 AM debugging. Trace conversations, replay events, inspect agent state, all without restarts.</p>
                <div class="feature-tools">
                    <span class="tool">caxton trace</span>
                    <span class="tool">caxton top</span>
                    <span class="tool">caxton replay</span>
                </div>
            </div>
            <div class="feature-card">
                <div class="feature-icon">🔌</div>
                <h3>Tool Integration</h3>
                <p>MCP (Model Context Protocol) bridges to external tools. Connect your agents to databases, APIs, and services.</p>
                <div class="feature-integrations">
                    <span class="integration">Database Tools</span>
                    <span class="integration">HTTP APIs</span>
                    <span class="integration">File Systems</span>
                </div>
            </div>
            <div class="feature-card">
                <div class="feature-icon">🌐</div>
                <h3>Distributed & Resilient</h3>
                <p>Built-in clustering with SWIM protocol. No external coordination service needed. Graceful handling of network partitions.</p>
                <div class="feature-distributed">
                    <span class="distributed">Auto-Discovery</span>
                    <span class="distributed">Partition Tolerance</span>
                    <span class="distributed">Self-Healing</span>
                </div>
            </div>
        </div>
    </div>
</section>

<!-- Three AM Test Section -->
<section id="three-am-test" class="three-am-test">
    <div class="container">
        <h2 class="section-title">The 3 AM Test</h2>
        <p class="section-subtitle">Every feature designed to be debugged in production</p>
        <div class="debugging-scenario">
            <h3>Real Debugging Scenario: Agent Conversation Timeout</h3>
            <div class="debug-steps">
                <div class="debug-step">
                    <div class="step-number">1</div>
                    <div class="step-content">
                        <h4>Alert fires: "Agent conversation timeout"</h4>
                        <pre><code>$ caxton trace --conversation-id abc123 --last 5m</code></pre>
                    </div>
                </div>
                <div class="debug-step">
                    <div class="step-number">2</div>
                    <div class="step-content">
                        <h4>See exactly where conversation stalled</h4>
                        <pre><code>[03:23:45.123] agent="OrderProcessor" message="propose" status="sent"
[03:23:45.567] agent="InventoryChecker" message="propose" status="received"
[03:23:50.568] agent="InventoryChecker" error="tool timeout" tool="database_query"</code></pre>
                    </div>
                </div>
                <div class="debug-step">
                    <div class="step-number">3</div>
                    <div class="step-content">
                        <h4>Root cause: Agent had a slow tool call</h4>
                        <pre><code>$ caxton debug agent InventoryChecker --show-metrics
Memory: 45MB/512MB | Queue: 1,523 messages | Tool calls: 15/s (p99: 5.2s)</code></pre>
                    </div>
                </div>
                <div class="debug-step">
                    <div class="step-number">4</div>
                    <div class="step-content">
                        <h4>Fix: Adjust circuit breaker configuration</h4>
                        <pre><code>$ caxton config set --agent InventoryChecker \
  --circuit-breaker.timeout=10s \
  --circuit-breaker.threshold=3</code></pre>
                    </div>
                </div>
            </div>
        </div>
    </div>
</section>

<!-- Architecture Section -->
<section id="architecture" class="architecture">
    <div class="container">
        <h2 class="section-title">Architecture</h2>
        <div class="architecture-content">
            <div class="architecture-text">
                <h3>Built for Production</h3>
                <p>Caxton follows type-driven development with a functional core and imperative shell architecture. Every architectural decision prioritizes debuggability and operational excellence.</p>
                <ul>
                    <li><strong>Agent Runtime</strong> - WebAssembly-based isolation and execution</li>
                    <li><strong>Message Router</strong> - FIPA protocol for semantic agent messaging across clusters</li>
                    <li><strong>Coordination Layer</strong> - SWIM protocol for membership, failure detection, and partition handling</li>
                    <li><strong>Observability Layer</strong> - OpenTelemetry integration from the ground up</li>
                    <li><strong>Tool Bridge</strong> - MCP protocol for external integrations and state management</li>
                    <li><strong>No External Dependencies</strong> - Everything built-in: SQLite for local state, SWIM for coordination</li>
                </ul>
                <div class="architecture-links">
                    <a href="{{ '/adr/' | relative_url }}" class="link-card">
                        <span class="link-icon">📚</span>
                        <span>View Architecture Decision Records</span>
                    </a>
                    <a href="{{ '/docs/' | relative_url }}" class="link-card">
                        <span class="link-icon">📖</span>
                        <span>Read Documentation</span>
                    </a>
                </div>
            </div>
            <div class="architecture-visual">
                <div class="architecture-views">
                    <h4>Three Views of the System</h4>
                    <div class="view-tabs">
                        <button class="view-tab active" data-view="logical">Logical View</button>
                        <button class="view-tab" data-view="physical">Physical View</button>
                        <button class="view-tab" data-view="failure">Failure View</button>
                    </div>
                    <div class="view-content">
                        <div class="view-pane active" id="logical-view">
                            <div class="architecture-diagram logical-view">
                                <div class="api-layer">
                                    <h5>External API</h5>
                                    <div class="api-endpoint grpc">gRPC API<br><small>:50051</small></div>
                                    <div class="api-endpoint rest">REST Gateway<br><small>:8080</small></div>
                                </div>
                                <div class="agent-layer">
                                    <h5>Deployed Agents</h5>
                                    <div class="agents-container">
                                        <div class="agent hexagon healthy">
                                            <span class="agent-name">Order<br>Processor</span>
                                        </div>
                                        <div class="agent hexagon healthy">
                                            <span class="agent-name">Inventory<br>Checker</span>
                                        </div>
                                        <div class="agent hexagon initializing">
                                            <span class="agent-name">Payment<br>Handler</span>
                                        </div>
                                    </div>
                                </div>
                                <div class="message-flow">
                                    <div class="message fipa">
                                        <span class="message-type">FIPA: propose</span>
                                        <span class="correlation-id">correlation: abc123</span>
                                    </div>
                                </div>
                                <div class="tool-layer">
                                    <h5>MCP Tool Bridge</h5>
                                    <div class="tools-container">
                                        <div class="mcp-tool">Database</div>
                                        <div class="mcp-tool">External API</div>
                                        <div class="mcp-tool">File System</div>
                                    </div>
                                </div>
                            </div>
                        </div>
                        <div class="view-pane" id="physical-view">
                            <div class="architecture-diagram physical-view">
                                <div class="system-boundary">
                                    <h4>caxton-server (systemd service)</h4>
                                    <div class="components">
                                        <div class="component api-gateway">
                                            <strong>API Gateway</strong><br>
                                            <small>:8080 (REST)<br>:50051 (gRPC)</small>
                                        </div>
                                        <div class="component actor-system">
                                            <strong>Actor System</strong><br>
                                            <small>tokio runtime<br>message routing</small>
                                        </div>
                                        <div class="component wasm-pool">
                                            <strong>WASM Runtime</strong><br>
                                            <small>wasmtime<br>512MB/instance</small>
                                        </div>
                                    </div>
                                    <div class="data-layer">
                                        <h5>Coordination Layer</h5>
                                        <div class="data-stores">
                                            <div class="store">Local State<br><small>SQLite (embedded)</small></div>
                                            <div class="store">Cluster Info<br><small>SWIM Protocol</small></div>
                                            <div class="store">Configuration<br><small>TOML files</small></div>
                                        </div>
                                    </div>
                                    <div class="observability">
                                        <h5>Observability Exports</h5>
                                        <div class="exports">
                                            <div class="export">Prometheus<br><small>:9090</small></div>
                                            <div class="export">OTLP<br><small>:4317</small></div>
                                            <div class="export">Health<br><small>:8081</small></div>
                                        </div>
                                    </div>
                                </div>
                            </div>
                        </div>
                        <div class="view-pane" id="failure-view">
                            <div class="architecture-diagram failure-view">
                                <div class="failure-zones">
                                    <div class="isolation-boundary">
                                        <h5>WebAssembly Isolation</h5>
                                        <div class="agent-failure crashed">
                                            <div class="crashed-agent">
                                                <span class="agent-name">Failed Agent</span>
                                                <span class="crash-icon">💥</span>
                                            </div>
                                            <div class="impact-indicator">
                                                <span class="impact-label">Blast Radius:</span>
                                                <span class="impact-value">ZERO</span>
                                            </div>
                                        </div>
                                        <div class="healthy-agents">
                                            <div class="agent-ok">Other Agent ✓</div>
                                            <div class="agent-ok">Other Agent ✓</div>
                                        </div>
                                    </div>
                                    <div class="recovery-mechanisms">
                                        <h5>Recovery Hierarchy</h5>
                                        <div class="supervision-tree">
                                            <div class="supervisor root">Root Supervisor</div>
                                            <div class="supervisor-arrow"></div>
                                            <div class="supervisor agent">Agent Supervisor</div>
                                            <div class="supervisor-arrow"></div>
                                            <div class="restart-policy">
                                                <span>Restart Policy:</span>
                                                <span>Max 3 restarts/min</span>
                                            </div>
                                        </div>
                                    </div>
                                    <div class="protection-layer">
                                        <h5>Circuit Breakers</h5>
                                        <div class="circuit-breakers">
                                            <div class="breaker open">
                                                <span class="breaker-name">External API</span>
                                                <span class="breaker-state">OPEN</span>
                                            </div>
                                            <div class="breaker closed">
                                                <span class="breaker-name">Database</span>
                                                <span class="breaker-state">CLOSED</span>
                                            </div>
                                        </div>
                                    </div>
                                    <div class="debug-layer">
                                        <h5>Debug Points</h5>
                                        <div class="debug-points">
                                            <div class="debug-point">Distributed Traces</div>
                                            <div class="debug-point">Structured Logs</div>
                                            <div class="debug-point">Metrics & Alerts</div>
                                            <div class="debug-point">Health Endpoints</div>
                                        </div>
                                    </div>
                                </div>
                            </div>
                        </div>
                    </div>
                </div>
            </div>
        </div>
    </div>
</section>

<!-- Getting Started Section -->
<section id="getting-started" class="getting-started">
    <div class="container">
        <h2 class="section-title">Getting Started</h2>
        <p class="section-subtitle">From zero to multi-agent system in 5 minutes</p>
        <div class="steps-grid">
            <div class="step-card">
                <div class="step-number">1</div>
                <h3>Install Caxton</h3>
                <div class="code-snippet">
                    <pre data-language="BASH"><code># Install with observability stack included
curl -sSL https://caxton.dev/install.sh | sh
caxton init my-system --with-observability</code></pre>
                </div>
            </div>
            <div class="step-card">
                <div class="step-number">2</div>
                <h3>Create Your First Agent</h3>
                <div class="code-snippet">
                    <pre data-language="BASH"><code># Create an agent from template
caxton agent create order-processor \
  --template request-handler \
  --capability order-processing</code></pre>
                </div>
            </div>
            <div class="step-card">
                <div class="step-number">3</div>
                <h3>Deploy and Monitor</h3>
                <div class="code-snippet">
                    <pre data-language="BASH"><code># Start with full observability
docker-compose up  # Includes Jaeger, Prometheus
caxton deploy
caxton monitor --dashboard</code></pre>
                </div>
            </div>
        </div>
        <div class="quick-example">
            <h3>Simple Multi-Agent Example</h3>
            <div class="steps-grid">
                <div class="step-card">
                    <div class="step-number">1</div>
                    <h3>Define Your Agent Configuration</h3>
                    <div class="code-snippet">
                        <pre data-language="YAML"><code># agent-config.yaml
name: order-processor
version: 1.0.0
runtime: wasm
capabilities:
  - order-processing
  - inventory-checking
resources:
  memory: 128MB
  timeout: 30s</code></pre>
                    </div>
                </div>
                <div class="step-card">
                    <div class="step-number">2</div>
                    <h3>Deploy to Caxton Server</h3>
                    <div class="code-snippet">
                        <pre data-language="BASH"><code># Deploy your compiled WebAssembly agent
caxton agent deploy order-processor.wasm \
  --config agent-config.yaml \
  --replicas 3

# Verify deployment
caxton agent status order-processor
✓ Running (3/3 instances healthy)</code></pre>
                    </div>
                </div>
                <div class="step-card">
                    <div class="step-number">3</div>
                    <h3>Invoke Your Agent</h3>
                    <div class="code-snippet">
                        <pre data-language="JS"><code>// Using any language with the Caxton client
const client = new CaxtonClient('https://caxton.local');

const result = await client.invoke('order-processor', {
  order: {
    items: ['item-123', 'item-456'],
    address: { street: '123 Main St', ... }
  }
});

console.log(result.tracking_number);</code></pre>
                    </div>
                </div>
            </div>
        </div>
    </div>
</section>

<!-- Resources Section -->
<section id="resources" class="resources">
    <div class="container">
        <h2 class="section-title">Resources</h2>
        <div class="resources-grid">
            <a href="https://docs.rs/caxton/latest/caxton/" target="_blank" rel="noopener" class="resource-card">
                <div class="resource-icon">📖</div>
                <h3>API Documentation</h3>
                <p>Complete Rust API reference on docs.rs</p>
            </a>
            <a href="{{ '/adr/' | relative_url }}" class="resource-card">
                <div class="resource-icon">🏛️</div>
                <h3>Architecture Decisions</h3>
                <p>Understand the why behind every architectural choice</p>
            </a>
            <a href="#releases" class="resource-card">
                <div class="resource-icon">📦</div>
                <h3>Releases</h3>
                <p>Latest updates, changelog, and roadmap</p>
            </a>
            <a href="{{ site.social.github }}/discussions" target="_blank" rel="noopener" class="resource-card">
                <div class="resource-icon">💬</div>
                <h3>Community</h3>
                <p>Join discussions, get help, contribute</p>
            </a>
        </div>
    </div>
</section>

<!-- Releases Section -->
<section id="releases" class="releases">
    <div class="container">
        <h2 class="section-title">Latest Release</h2>
        <div class="release-card">
            <div class="release-status">
                <span class="status-badge">{% if site.data.release %}{{ site.data.release.status }}{% else %}Early Development{% endif %}</span>
                <span class="release-date">
                    {% if site.data.release.version and site.data.release.version != "0.1.0-dev" %}
                        v{{ site.data.release.version }} • {{ site.data.release.date }}
                    {% else %}
                        Project Status
                    {% endif %}
                </span>
            </div>
            <h3 class="release-title">
                {% if site.data.release %}
                    {% if site.data.release.version == "0.1.0-dev" or site.data.release.version contains "0." %}
                        {{ site.data.release.phase | default: "Foundation Phase" }}
                    {% else %}
                        {{ site.data.release.name }}
                    {% endif %}
                {% else %}
                    Foundation Phase
                {% endif %}
            </h3>
            <div class="release-description">
                {% if site.data.release.version and site.data.release.version contains "0." %}
                    Caxton is currently in early development. Core architecture is being implemented with a focus on
                    getting the fundamentals right: WebAssembly isolation, FIPA messaging, and comprehensive observability.
                {% elsif site.data.release and site.data.release.description %}
                    {{ site.data.release.description | markdownify | truncate: 300 | strip_html }}
                {% else %}
                    Caxton is currently in early development. Core architecture is being implemented with a focus on
                    getting the fundamentals right: WebAssembly isolation, FIPA messaging, and comprehensive observability.
                {% endif %}
            </div>
            <div class="release-actions">
                {% if site.data.release and site.data.release.url and site.data.release.version != "0.1.0-dev" %}
                <a href="{{ site.data.release.url }}" target="_blank" rel="noopener" class="btn btn-outline">
                    View Release Notes
                </a>
                {% endif %}
                <a href="{{ site.social.github }}/releases" target="_blank" rel="noopener" class="btn btn-outline">
                    View All Releases
                </a>
                <a href="{{ site.social.github }}/blob/main/ROADMAP.md" target="_blank" rel="noopener" class="btn btn-outline">
                    View Roadmap
                </a>
            </div>
        </div>
    </div>
</section>