« Phase 01 · Warmup · Track Overview

Lab 01 — The Agent Kernel

The problem

Thirty teams want to run agents on your platform. Each of them will, if you let them, write their own loop — and each of those loops will forget the step budget, keep state in process memory, grow the context until the run dies, and log nothing an auditor can use.

Your job is to make that unnecessary. You build the kernel: the runtime that owns the lifecycle, enforces the budgets, externalizes the state, manages the memory tiers, and emits the execution chain. Agent authors bring a goal, a tool set, and a policy. Everything else is yours.

The OS analogy is exact and worth holding onto: a process does not choose its own memory limit, is not trusted to yield the CPU voluntarily, and cannot decide where its page tables live. Neither should an agent.

What you build

Key concepts

Files

Run

pip install -r requirements.txt
pytest test_lab.py -v
LAB_MODULE=solution pytest test_lab.py -v
python solution.py

Success criteria

• All 60 tests green against your lab.py.
• Every terminal state rejects every event — the test iterates all of them.
• No state is a trap: every non-terminal state has an edge to a terminal state.
• compact_if_needed returns False when under budget and when the only steps left are the recent window.
• SemanticMemory.search returns [] for a caller holding no scope, whatever the tags.
• A stale save raises ConcurrentModification — it does not silently overwrite.
• Two AffinityRouters built with different insertion order route identically.
• Adding a replica to a 3-node ring moves between 10% and 45% of sessions, and every moved session goes to the new replica (no churn between existing ones).
• The policy is called exactly max_steps times when an agent loops — not max_steps + 1.
• execution_chain still has every step after a compaction.

How this maps to the real stack

Honest limits. The kernel is single-process and synchronous. It does not do parallel tool calls, streaming, multi-agent fan-out, or true durable execution across a crash mid-tool-call (the checkpoint happens after the observation, so a crash during dispatch replays the call — which is precisely why the action gateway's idempotency keys in Phase 10 are not optional).

Extensions

1. Crash-safe dispatch. Checkpoint before the tool call with the call recorded as in_flight, and on resume either re-dispatch with the same idempotency key or reconcile. That is the difference between "checkpointed" and "durable."
2. Parallel tool calls. Let a Decision carry several tool calls, dispatch them concurrently, and merge observations deterministically (sort by tool name) so the trace stays diffable.
3. Streaming. Yield partial steps from run() as a generator and assert the stream is a prefix-consistent view of the final result.
4. Capacity-weighted ring. Give each replica a weight and allocate virtual nodes proportionally; verify the distribution matches the weights.
5. Memory promotion. Add a rule that promotes a fact observed in three episodes into SemanticMemory, with provenance — then think hard about what that means for the audit trail.
6. A second planner. Implement ReWOO (plan the whole chain up front, execute, then solve) as an alternative run() mode, and compare step counts and token totals on the same policy.

Interview / resume bullets

• "Built the platform's agent kernel: an explicit lifecycle state machine with a provable transition table, kernel-enforced step/token/cost/deadline budgets, externalized session state with optimistic concurrency, and an execution chain that doubles as the audit artifact."
• "Made session affinity an optimization rather than a requirement by externalizing state, then implemented consistent-hash routing with draining so a rolling deploy moves ~1/n of sessions instead of all of them."
• "Cut long-run token cost by adding scratchpad compaction that folds old steps into a summary while preserving the recent window — attacking the quadratic growth term without losing the full record, which stays in the checkpointed chain."
• "Classified agent failures into recoverable (a hallucinated tool name feeds back as an observation) and fatal (a budget breach ends the run), which turned a class of agent bugs into self-correction instead of incidents."