savarin

← Back to Index

Chapter 1 — The Turn That Couldn't Crash

The v1 runtime worked. Turns completed, tools executed, users got replies. If you ran it in production, it did what it was supposed to do. But if you tried to write a test for the turn loop in isolation — to drive just the loop, with a fake model and no platform connection — you couldn't. The platform and the loop were fused. Every improvement to the turn hit the same wall. That's not a bug. That's a ceiling.

This chapter is about how that ceiling forms, what it looks like in code, and why the only way past it is to change the shape rather than patch the contents.

1.1 What a Turn Is

savarin

← Back to Index

Terminology Register — Pass 2

Canonical forms established during copy-edit Pass 2 of Chapters 1–5. All subsequent chapters should match these.

Note: Code identifiers use Python conventions (snake_case for functions/variables, PascalCase for classes/protocols). The underlying source codebase is TypeScript; these are the Python-edition canonical forms.

---

savarin

← Back to Index

Parts Summary

14 chapters across 7 parts (Part 0 through Part VI). Parts are warranted: the book covers distinct architectural layers (contracts → durability → tools → composition → distribution), each with its own design vocabulary and failure modes. The parts mirror the order in which a runtime designer encounters these concerns — you can't think about distribution until you've settled the turn model.

---

Part 0 · The Rewrite Decision (Chapters 1–2)

savarin

← Back to Index

Chapter Inventory

14 chapters organized into 7 parts (Part 0 through Part VI). Each part asks one question about agent runtime design; its chapters answer by reading v1 and v2 side by side.

---

Part 0 · The Rewrite Decision

savarin

← Back to Index

The Rewrite

Building an Agent Runtime from First Principles

---

You've built a chatbot. Maybe you've wired up tool calling — a function the model can invoke, a schema it can fill. You've seen the demos: an agent that books flights, writes code, searches the web. The loop is simple: prompt, tool call, result, repeat.

savarin

The Rewrite: Python Edition

Why throw away 132 working files and start over? This book follows a real rewrite of an agent runtime — v1 forked from an agent engine, v2 built from the ground up — and examines 14 dimensions where the two made different choices. Code examples are presented in Python.

---

Front Matter

• Back Cover — Audience, promise, and key takeaways
• Chapter Inventory — All chapters with one-line descriptions

savarin

Why the Variant Report Numbers Don't Match

What We Do for Coterie

We run email experiments for Coterie — when a customer abandons their cart or browses a product, Klaviyo (the email platform) decides whether to send them a Neon Blue-optimized email or Coterie's original. Our system picks the best variant for each user.

There's a report that shows how these experiments are performing. Antoine noticed the numbers didn't add up: the summary at the top said one thing, and the detailed breakdown below said something different. For some experiments, the summary showed 5x more users than the detail rows. For others, it was the reverse.

What We Found

savarin

Why the Variant Report Numbers Don't Match

What We Do for Coterie

We run email experiments for Coterie — when a customer abandons their cart or browses a product, Klaviyo (the email platform) decides whether to send them a Neon Blue-optimized email or Coterie's original. Our system picks the best variant for each user.

There's a report that shows how these experiments are performing. Antoine noticed the numbers didn't add up: the summary at the top said one thing, and the detailed breakdown below said something different. For some experiments, the summary showed 5x more users than the detail rows. For others, it was the reverse.

What We Found

savarin

How to Update coterie-variant-performance-evaluation

A step-by-step guide for refreshing the Coterie variant performance evaluation pipeline. All scripts live in tasks/coterie-variant-performance-evaluation/scripts/ unless noted. Requires AWS_PROFILE=neonblue-production.

---

Pipeline Overview

savarin

Updating coterie-variant-performance-evaluation

What this report is

Treatment-vs-control results for Coterie's email A/B experiments. Each experiment is a Klaviyo flow with a conditional split: users on an NB whitelist (RHp5HP) get NB-optimized emails (treatment), everyone else gets the original Coterie emails (control). 10 experiments, each measured on a primary metric (subscription adds, first orders, etc.).

The report renders at http://localhost:3000/reports/coterie-variant-performance-evaluation from report.json.

Setup