Architecture notes · build-in-public

Why the coach runs a bounded agentic loop

The decision: build the loop, then bound it

The design spec set this direction before any code was written: build the coach "as a real agentic loop, not a chat wrapper," with the loop shape send → check stop_reason → if tool_use: run tool + append result → loop → end_turn, and — this is the load-bearing instruction — "Bound it: turn/tool budget + done-condition + escalation (this is the module's lesson, applied)." That sentence is in the design doc's coach section, and the coach module it refers to (trackB.m2.agentic-loop) is the canonical reference content the rest of the catalog is authored against.

So the loop wasn't bounded as an afterthought once it misbehaved. The bound was a design requirement, because the whole product premise is that you learn the discipline by building the thing that needs the discipline.

What the bound actually is

Two hard caps live at the top of the coach loop, as named constants, with the rationale in the comment beside them:

// Bounded agency (OWASP LLM06): hard caps on model turns and tool calls so the
// loop can never run away. These are the safeguard the module itself teaches.
export const MAX_TURNS = 6;
export const MAX_TOOL_CALLS = 8;

The loop runs while (turns < MAX_TURNS). On each turn it streams a model response, collects any tool_use blocks, and inspects the stop reason. If the model stopped to call tools, the loop dispatches each one — but first checks the running tool count against MAX_TOOL_CALLS. Cross that line and the loop emits an explicit annotation and stops rather than continuing:

// inside the tool-dispatch path, before running a tool:
if (toolCalls >= MAX_TOOL_CALLS) {
  yield { type: 'annotation',
    text: 'Tool-call budget reached — escalating to a human/stopping ' +
          '(bounded agency, OWASP LLM06).' };
  yield { type: 'done', stop_reason: 'tool_budget' };
  return;
}

If instead the model stops on its own (end_turn), the loop yields done and returns — the normal exit. And if the turn budget runs out before the model is satisfied, the loop emits a max_turns annotation and stops "to avoid a runaway loop." Three budget exits, all explicit: the model is done, the tool budget is spent, or the turn budget is spent. The loop returns early on two more — the input judge blocking a turn, the output scanner blocking one — and degrades to a graceful in-band reply on any error. Every branch returns; there is no path where the loop just keeps going.

The tools are least-privilege on purpose

Bounding the loop is only half of "excessive agency." The other half is what the agent is allowed to touch. The tool surface, documented at the top of the coach module, is eight tools: fetch the learner's due review items, retrieve lesson context for grounding, grade an attempt the learner actually made, schedule a review, read mastery state, search the live AWS docs, search the live Cloudflare docs, and record one small fact about the learner for future sessions. The source comment states the constraint directly: "LEAST PRIVILEGE — coach has NO write access to content/billing."

Three of those tools do write — grading, scheduling a review, and memory — and the precision matters more than a blanket "read-only" claim would: all three write the learner's own learning state and nothing else. They also carry a second latch. Once a turn has pulled in an external document through one of the doc searches, learning-state writes are refused for the remainder of that turn and the refusal is audited. A doc page carrying an injection can still try to talk the model into something; it cannot get the learner's record changed on the strength of it.

Grading is the sharp edge here. The coach does not get a private path to answer keys: when it grades an attempt, it calls the same shared grader the public attempt endpoint uses (src/lib/grade.ts). There's one grader, and answer keys are only ever revealed after a learner has answered — a rule the system prompt also enforces in words ("never hand over an exam answer key verbatim").

One subtlety the loop has to respect

A bounded loop that stops on a budget can produce a turn that is only an annotation. The repo's worker-code notes flag the consequence: the coach must always persist a non-empty assistant turn, because an annotation-only budget turn would otherwise leave two consecutive user roles in the stored history — which the live Anthropic API rejects with a 400 on the next call. The end-of-turn write is a three-way fallback for exactly that reason: the streamed text, or failing that the last annotation, or failing that a literal (no reply) placeholder. So the bound isn't just a safety feature in the abstract; it forced a concrete invariant on how conversation history is recorded. That's the kind of detail you only find by building the loop for real.

Where the state lives

The conversation lives in a SQLite-backed Durable Object — CoachAgent, a Cloudflare Agents SDK Agent subclass — and there is exactly one instance per learner, addressed by the Clerk-authenticated userId via getAgentByName, never by an id the client supplies. Sessions are not separate objects: they are rows, keyed by a session_id column in that agent's own messages table. The distinction is worth more than it looks. Because every one of a learner's sessions resolves to the same instance, per-learner state has exactly one home — so the in-flight-turn guard and the turn-rate limiter held in that instance's memory are a genuine global cap for that learner, not the per-isolate best-effort the same code would be in a stateless worker.

The transport is a WebSocket. GET /api/coach/ws checks entitlement, rate-limits the connection, resolves the learner's agent, and forwards the upgrade with an internal header carrying the verified user id — the only identity the agent will accept. The loop runs inside the agent: it gathers recent history, mastery and memory, iterates runCoachLoop, and writes each event out as a frame.

What the agent deliberately does not hold is logic. The unit tests can't import the agents package at all, so anything living inside the Durable Object is untestable — which is why the class is held to plumbing only (parse, guard, call the loop, write frames, persist) and the loop itself stays in src/lib/coach.ts where the tests are. The same rule confines agents imports to four files, so an SDK change has a small, known blast radius. Choosing a SQLite-backed Durable Object also kept this side of the system on Cloudflare's free plan; Vectorize, later, is what required the paid one.

The honest part: it's evaluated, not asserted

A bounded loop that's never tested is a comment, not a guarantee. The loop ships with a dependency-injection seam — the stream function can be swapped — so a test can inject a model that always asks for another tool and prove the loop still terminates within its budget. That termination test, plus the offline round-trip, is what turns "the loop is bounded" from intention into something CI checks. The coach also carries a small eval set (corrective, grounded/cited, misconception-targeting, in-scope, terminates) that runs on every prompt change, because evals are both the safeguard and the single skill this curriculum most wants you to be able to demonstrate.