Previous article：Agent Loop: Observe, Decide, Act in a Coding Agent
Next article：Context Builder for AI Coding Agents
中文版：Transcript Logging：Agent 执行日志与可观测性

Introduction

Day 07: record model requests, tool calls, results, errors, and timings as replayable JSONL transcripts. This chapter keeps the implementation deliberately small: the point is to make one boundary explicit, testable, and easy to inspect before adding more autonomy.

Why transcript data matters

A coding agent is more than a model response. It needs a runtime that can turn a request into controlled work, preserve the intermediate state, and explain what happened afterwards. Day 07 focuses on that runtime boundary instead of hiding it behind a single prompt.

run start → model request → tool call → tool result → final answer or error → run end

A useful JSONL event model

The implementation uses explicit data structures and narrow interfaces. The model proposes the next step; the harness owns validation, execution, limits, and structured results. That separation lets the same capability work in a CLI today and in a richer product surface later.

• Record a stable event type for every meaningful transition.
• Keep model input, tool input, result, and timing separately inspectable.
• Write one JSON object per line so a run can be streamed or replayed.

Recording failures without hiding them

Reliability comes from treating failure paths as normal paths. Inputs are bounded, unsafe or malformed requests produce recoverable errors, and the run records enough evidence to let a developer understand the decision. This is especially important when later steps can touch a real workspace.

observe -> decide -> act -> observe -> final

npm run dev -- --transcript logs/runs/day-07.jsonl "inspect the repo and summarize the structure"

run_started
model_request
model_response
tool_call
tool_result
model_request
model_response
tool_call
tool_result
model_request
model_response
run_finished

How to replay and debug a run

With this layer in place, later chapters can add capability without weakening the boundary: tools can be registered and observed, context can be measured, writes can require approval, and every run can be replayed. The result is not a general autonomous system; it is a compact harness whose behavior remains understandable.

Key takeaways

• Build the execution boundary before adding more tools or model freedom.
• Keep model intent separate from runtime authority.
• Make limits, validation, and failure results visible.
• Use structured observations to support debugging and future extensions.

Demo

The accompanying implementation and runnable examples are available in the cli-harness repository.