boxmaker/docs/plans/M2b/06-loopd-turn.md

M2b task 06: one turn

Branch: m2b (run git switch m2b; git status --short must be empty, otherwise stop) Commit subject: Add the turn loop with its limits

Goal

A user message in, an answer out, with tool calls in between and a limit on every kind of runaway. This is the centre of M2b. Two test files define it: turn.rs for the record sequences and the tool path, limits.rs for the limits and for the append-only property over generated conversations.

Context

From the brief: "Runaway control. Per-turn thinking-token cap, per-turn tool-iteration cap, detection of repeated identical tool calls." The thinking cap is in M2a. The other two are here, with two more: a full context, and the size of a tool result.

The recordings used by the tests were made in separate conversations, so their cache numbers do not line up. The loop will rightly write CacheLoss records between them; the tests allow for that.

Files

• Copy: crates/loopd/tests/turn.rs, crates/loopd/tests/limits.rs, crates/loopd/tests/support/turn.rs, and three recordings into crates/loopd/tests/fixtures/http/: find_tool.http, call_tool.http, context_full.http
• Create: crates/loopd/src/turn.rs
• Modify: crates/loopd/src/lib.rs, docs/implementer-log.md

Interfaces

pub enum TurnError { SessionFull, TurnLimit, Infer(InferError), Session(SessionError) }   // Debug; Display; Error; From<SessionError>
pub struct TurnOutcome { pub content: String, pub usage: proto::Usage }                    // Debug, Clone, PartialEq, Eq

/// What a turn needs besides the session.
pub struct Runtime<'a> { pub cfg: &'a Config, pub client: &'a Client, pub port: &'a dyn ToolPort, pub registry: &'a Registry }

/// True for the one 400 the server sends when the prompt does not fit.
pub fn is_context_full(error: &InferError) -> bool;

pub fn run_turn(session: &mut Session, rt: &Runtime<'_>, content: &str, on_event: &mut dyn FnMut(&TurnEvent)) -> Result<TurnOutcome, TurnError>;

is_context_full: Http { status: 400, body } whose body is JSON with error.type equal to "exceed_context_size_error". Look at fixtures/http/context_full.http to see one.

What run_turn does

1. Append User { time: now, content }.
2. Build a ChatRequest: slot: cfg.slots.main, messages: messages(baseline, records), tools: baseline.tools.clone(), thinking: true. Remember session.last_usage() from before this completion.
3. client.chat_with_retry. Map each ChatEvent to a TurnEvent and pass it on: Queued, Waiting, Progress, Reasoning, Content, ThinkingCapped, Retrying map one to one; ToolCallDelta is dropped (the channel gets ToolCallStarted later instead). On Err(e): if is_context_full(&e), return SessionFull; else return Infer(e). Nothing is appended for the failed request.
4. Append Assistant with the completion's three fields, then Usage with its timings, reasoning_tokens and thinking_capped. If there was an earlier usage, run cache_outcome on its timings and the new ones; on a Loss, append CacheLoss and emit TurnEvent::CacheLoss.
5. No tool calls: return TurnOutcome { content: content.unwrap_or_default(), usage }.
6. Otherwise count one iteration; if the count exceeds cfg.loop.tool_iterations, return TurnLimit. Then for each tool call in order: a. Emit ToolCallStarted { name }. Take session.next_call() as this call's id. b. Repeat detection, when cfg.loop.repeat_detection: the pair (name, arguments) has been seen in this turn already. The first repeat is not run; its result text says the call was already made with these arguments in this turn. A second repeat returns TurnLimit. c. Otherwise dispatch(registry, name, arguments). Local(text) is the result, with class Public and untrusted: false. Port { tool, arguments } builds a ToolRequest with the session id and the call id and sends it to the port; Result gives its content, class and untrusted flag; Failed { message } gives "The tool failed: …", Public, not untrusted; Denied { reason } gives "The call was denied: …"; PendingApproval gives a text saying this version cannot wait for approval. d. cap_result(text, cfg.loop.tool_result_cap), then append ToolResult { time, call, tool_call_id: <the model's call id>, content, class, untrusted, truncated }, then emit TurnEvent::ToolResult { name, class, truncated }.
7. Back to step 2.

Every time is Timestamp::now(). It goes into the log only, never into a message.

Steps

• 1. Copy.

git switch m2b
cp docs/plans/M2b/files/crates/loopd/tests/turn.rs docs/plans/M2b/files/crates/loopd/tests/limits.rs crates/loopd/tests/
cp docs/plans/M2b/files/crates/loopd/tests/support/turn.rs crates/loopd/tests/support/
cp docs/plans/M2b/files/crates/loopd/tests/fixtures/http/*.http crates/loopd/tests/fixtures/http/

Read limits.rs first: each limit has a test, and the last test is the property the milestone exists to prove.

• 2. See the tests fail. cargo test -p loopd --test turn. Expected: it does not compile.
• 3. Write turn.rs and add pub mod turn; to lib.rs. Run cargo fmt --all.
• 4. See the tests pass. cargo test -p loopd --test turn --test limits. Expected: 9 passed and 6 passed.
• 5. Check the limits yourself. For each of the five limits in the spec's table (tool iterations, repeated call, thinking cap, context full, tool result size), name the test that covers it. Put the list in your log row.
• 6. Run the gate. make gate. Expected last line: gate: ok.
• 7. Log and commit. git add crates/loopd docs/implementer-log.md && git commit

Done when

• cargo test -p loopd --test turn --test limits reports 9 and 6 passed; make gate prints gate: ok.
• turn.rs is under 300 lines. If it is not, something is being done twice.

Stop and report if

• every_request_extends_the_previous_one fails. Do not change the seeds or the test; the seed is printed so that the case can be replayed.