What Layers Make Up a Coding Agent: the REPL Skeleton, the Command System, and a Provider-Neutral Gateway Abstraction

Today's Goals

1. Draw a terminal Coding Agent's layer diagram, and explain each layer's inputs, outputs, and cost to replace
2. Hand-write a REPL with slash commands, separating command parsing from conversation logic
3. Write an OpenAI-compatible gateway abstraction that switches between different providers and an offline script using only environment variables

Plain-Language Walkthrough

What we are building equals onboarding a new hire onto an unfamiliar repo

Suppose a new hire starts today and you need them working in a repository they have never seen. How do you onboard them?

On day one you give them no permissions at all, just a seat and the ability to talk to you. On day two you want them thinking out loud rather than disappearing for an hour and handing you a report. On day three you grant read access to the code. Only on day four do they start editing, and they must be able to run the tests to check themselves. On day five you agree on which calls they make alone and which need asking first. After that: how to correct a mistake, how to hand over at the end of a shift, where to write down what they cannot remember, how to split work when there is too much of it.

The next twenty-one days write that process into code one day at a time. The artifact is called mca, a Coding Agent that runs in your terminal. On day twenty-one it is a globally installable command-line tool: type a sentence in any repository and it reads code, edits files, runs tests, asks permission by your rules, and can roll its changes back afterwards.

Two boundaries first, so expectations line up.

One: everything is implemented by hand. No LangChain, no vendor SDK, no off-the-shelf MCP client library — even command-line argument parsing and terminal colors are written from scratch. The project's only runtime dependency is a small tool that reads .env. This is not showing off: a Coding Agent's substance lies exactly in the parts frameworks hide — how streaming is parsed, how tool-call arguments are assembled, how approval is inserted into the loop, how a full context is trimmed. A framework gets you something that runs, and you learn none of that, and cannot answer for it in an interview.

Two: it must run every day. Whatever layer you finish today has a command that shows you something today — and without a model key too, which the second half of today delivers.

Five layers: which are yours and which belong to the provider

Look at the end state first. A terminal Coding Agent has five layers, and the arrows are data flow:

flowchart TD
  A[interaction: REPL, commands, rendering, interruption] -->|one line of input| B[session: message array, event log, resume and fork]
  B -->|one run request| C[Agent Loop: iterate until the model stops asking for tools]
  C -->|messages plus tool list| D[gateway: send the request, translate the deltas back]
  C -->|one tool call| E[tools: read files, edit files, run commands]
  D -->|stream deltas| C
  E -->|tool results| C
  C -->|semantic events| A

The valuable information in that diagram is not "there are five layers" but each layer's inputs and outputs, because that is what decides whether you can replace one layer alone.

Hence this course's first design rule: no provider type may appear inside the Agent Loop. The loop knows only two type families you defined yourself — the deltas the gateway emits and the semantic events the loop emits — with all translation sealed inside the gateway layer. Why care so much? Because the loop is the most-edited file of the twenty-one days: streaming render events tomorrow, tool execution on day three, approval on day five, retry and cancellation on day six, compaction on day twelve. If it also has to track provider wire formats, every model switch means surgery on your most complex file.

Why the gateway abstraction belongs on day one: a model id's shape is not a constant

A beginner's first Agent code usually looks like this: a hard-coded URL, a hard-coded model name, and a function calling fetch directly. It runs, and then it collapses in week three — because you want to switch to a cheaper gateway and find the model name is written differently.

How concretely? On 7 September 2026 I measured two OpenAI-compatible gateways: for the same model, one wants a vendor-prefixed form (for example openai/gpt-4o-mini) and the other wants the upstream name (for example claude-haiku-4-5-20251001). Their endpoint paths, auth headers and request body fields are all identical; only the shape of the model id differs.

The conclusion is plain: base URL, key and model id must all be configuration, never hard-coded and never assumed to have a particular format. So this whole course knows exactly three environment variables:

LLM_BASE_URL=https://openrouter.ai/api/v1   # any OpenAI-compatible gateway
LLM_API_KEY=sk-...                          # a key issued by that gateway
LLM_MODEL=openai/gpt-4o-mini                # a model id that gateway accepts

Plus one switch, MOCK=1: run the offline script and send no network requests. Across twenty-one days, none of those four changes.

The gateway layer's interface has exactly one method, and only the streaming kind:

export type StreamDelta =
  | { type: 'text'; text: string }
  | { type: 'tool_call'; index: number; id?: string; name?: string; argsDelta?: string }
  | { type: 'usage'; promptTokens: number; completionTokens: number; cachedTokens: number }
  | { type: 'finish'; reason: 'stop' | 'tool_calls' | 'length' | 'other' }
 
export interface ChatProvider {
  readonly id: string
  readonly model: string
  stream(req: ChatRequest): AsyncIterable<StreamDelta>
}

from dataclasses import dataclass
from typing import AsyncIterator, Literal, Protocol
 
@dataclass
class TextDelta:
    text: str
 
@dataclass
class ToolCallDelta:
    index: int
    id: str | None = None
    name: str | None = None
    args_delta: str | None = None
 
@dataclass
class UsageDelta:
    prompt_tokens: int
    completion_tokens: int
    cached_tokens: int
 
@dataclass
class FinishDelta:
    reason: Literal["stop", "tool_calls", "length", "other"]
 
StreamDelta = TextDelta | ToolCallDelta | UsageDelta | FinishDelta
 
class ChatProvider(Protocol):
    id: str
    model: str
 
    def stream(self, req: "ChatRequest") -> AsyncIterator[StreamDelta]: ...

Why no non-streaming method? Because nothing in a Coding Agent uses one — you always want to see what it is thinking. An extra method is one more branch to keep in sync for twenty-one days.

The gateway provider's minimal implementation: one POST, one SSE stream, a run of deltas

Today's version deliberately parses text deltas only — tool-call fragments, half lines and stream interruptions are tomorrow's. Get the skeleton clear first:

export class GatewayProvider implements ChatProvider {
  readonly id = 'gateway'
 
  constructor(
    private readonly baseUrl: string,
    private readonly apiKey: string,
    readonly model: string
  ) {}
 
  async *stream(req: ChatRequest): AsyncIterable<StreamDelta> {
    const res = await fetch(`${this.baseUrl}/chat/completions`, {
      method: 'POST',
      headers: { authorization: `Bearer ${this.apiKey}`, 'content-type': 'application/json' },
      body: JSON.stringify({
        model: this.model,
        stream: true,
        stream_options: { include_usage: true },
        messages: req.messages.map((m) => ({ role: m.role, content: contentToText(m.content) })),
      }),
      signal: req.signal,
    })
    if (!res.ok || !res.body) {
      const detail = await res.text().catch(() => '')
      throw new Error(`gateway returned ${res.status}: ${detail.slice(0, 200)}`)
    }
 
    const decoder = new TextDecoder()
    let buffer = ''
    for await (const chunk of res.body as unknown as AsyncIterable<Uint8Array>) {
      buffer += decoder.decode(chunk, { stream: true })
      const lines = buffer.split('\n')
      buffer = lines.pop() ?? '' // the tail may be half a line; keep it for the next round
      for (const line of lines) {
        const trimmed = line.trim()
        if (!trimmed.startsWith('data:')) continue
        const payload = trimmed.slice(5).trim()
        if (payload === '[DONE]') return
        const delta = parseChunk(payload)
        if (delta) yield delta
      }
    }
  }
}

import json
import httpx
 
class GatewayProvider:
    id = "gateway"
 
    def __init__(self, base_url: str, api_key: str, model: str) -> None:
        self.base_url = base_url.rstrip("/")
        self.api_key = api_key
        self.model = model
 
    async def stream(self, req: "ChatRequest"):
        payload = {
            "model": self.model,
            "stream": True,
            "stream_options": {"include_usage": True},
            "messages": [
                {"role": m.role, "content": content_to_text(m.content)} for m in req.messages
            ],
        }
        headers = {"authorization": f"Bearer {self.api_key}"}
        async with httpx.AsyncClient(timeout=None) as client:
            async with client.stream(
                "POST", f"{self.base_url}/chat/completions", json=payload, headers=headers
            ) as res:
                if res.status_code >= 400:
                    detail = (await res.aread()).decode()[:200]
                    raise RuntimeError(f"gateway returned {res.status_code}: {detail}")
                # httpx's aiter_lines already handles framing, so no buffer is needed here
                async for line in res.aiter_lines():
                    line = line.strip()
                    if not line.startswith("data:"):
                        continue
                    payload_text = line[5:].strip()
                    if payload_text == "[DONE]":
                        return
                    delta = parse_chunk(json.loads(payload_text))
                    if delta is not None:
                        yield delta

One real difference between the versions is worth noting: in Node you must keep a buffer for half lines, because you receive byte chunks; Python's httpx offers line-wise iteration and has done the framing for you. That is not language superiority but a different level of abstraction — and tomorrow we will see that even line framing is not enough, because SSE's real boundary is the blank line.

Why slash commands must not share one if-statement with conversation

The REPL's main loop has three steps: read a line, decide whether it is a command or conversation, execute. It looks like two ifs. But twenty-one days later there will be a dozen commands: /help, /clear, /resume, /rewind, /compact, /context, /memory, /plan, /model and more, each with its own arguments and help text.

So from day one, commands are data, not control flow: a command table where each entry has a name, help text and a run function. The parser only splits a line into a command name and arguments; it does not even check whether the command exists — that is the caller's job.

export interface Command {
  name: string
  help: string
  run(args: string, session: Session): Promise<boolean> | boolean // false means exit
}
 
/** Parse one line into a command name and arguments; return null if it is not a command */
export function parseCommand(line: string): { name: string; args: string } | null {
  if (!line.startsWith('/')) return null
  const trimmed = line.slice(1).trim()
  const space = trimmed.indexOf(' ')
  if (space === -1) return { name: trimmed, args: '' }
  return { name: trimmed.slice(0, space), args: trimmed.slice(space + 1).trim() }
}

from dataclasses import dataclass
from typing import Awaitable, Callable
 
@dataclass
class Command:
    name: str
    help: str
    run: Callable[[str, "Session"], Awaitable[bool] | bool]  # False means exit
 
def parse_command(line: str) -> tuple[str, str] | None:
    """Parse one line into a command name and arguments; return None if not a command"""
    if not line.startswith("/"):
        return None
    name, _, args = line[1:].strip().partition(" ")
    return name, args.strip()

And one trap I hit while writing this day's lab: writing the REPL with question() from readline/promises hangs when input is piped in. Once stdin reaches its end, the promise it returns neither resolves nor rejects on some Node versions, and the process finally exits with code 13 complaining about an unsettled top-level await. Switching to node:readline's async iterator fixes it — the loop ends naturally when input ends, and both interactive and piped usage work. That matters especially in this course, because every day's acceptance pipes input in.

The offline script provider: reproduce the next twenty days' behavior for free

Now write the second provider. It sends no network requests and emits deltas from a script.

What matters is the script's quality. "Return one hard-coded fake reply" only proves the program did not crash; a useful script goes: say two sentences, then ask to call a tool, then draw a conclusion from the tool's result. So offline, the Agent really reads files, really edits files, really runs tests — only "what the model said" is fake, and everything else is real.

const CHUNK_SIZE = 4
const CHUNK_DELAY_MS = 12
 
export class MockProvider implements ChatProvider {
  readonly id = 'mock'
  constructor(readonly model: string) {}
 
  async *stream(req: ChatRequest): AsyncIterable<StreamDelta> {
    // Branch on the last user message, not on a turn counter - otherwise an injected
    // failure shifts the script out of alignment
    const lastUser = [...req.messages].reverse().find((m) => m.role === 'user')
    const scene = pickScene(contentToText(lastUser?.content ?? ''))
 
    for (const piece of splitText(scene.text)) {
      await sleep(CHUNK_DELAY_MS)
      yield { type: 'text', text: piece }
    }
    yield { type: 'usage', promptTokens: 0, completionTokens: estimateTokens(scene.text), cachedTokens: 0 }
    yield { type: 'finish', reason: 'stop' }
  }
}

import asyncio
 
CHUNK_SIZE = 4
CHUNK_DELAY = 0.012
 
class MockProvider:
    id = "mock"
 
    def __init__(self, model: str) -> None:
        self.model = model
 
    async def stream(self, req: "ChatRequest"):
        # Branch on the last user message, not on a turn counter
        last_user = next((m for m in reversed(req.messages) if m.role == "user"), None)
        scene = pick_scene(content_to_text(last_user.content) if last_user else "")
 
        for i in range(0, len(scene.text), CHUNK_SIZE):
            await asyncio.sleep(CHUNK_DELAY)
            yield TextDelta(scene.text[i : i + CHUNK_SIZE])
        yield UsageDelta(0, estimate_tokens(scene.text), 0)
        yield FinishDelta("stop")

Note the last two events: usage and finish reason. Without them the render layer sees no usage and the loop does not know to wrap up — the offline and real paths must emit the same event sequence, or logic you tuned offline falls apart the moment a real model is attached.

That is also why the stub sits on your own interface rather than on fetch: stubbing fetch stubs a wire format that changes with every gateway; stubbing your own provider interface stubs semantics, which do not move for twenty days.

Deliberately no streaming rendering today

One last thing, to leave you with a feeling. Today's render layer waits for the turn to end and prints the whole answer at once, followed by a line of statistics: how many deltas arrived, the time to first token, the total time.

Why skip the better approach knowing it exists? Because these two measured lines (7 September 2026, same gateway, same question) argue better than any explanation:

model A: first token 1832ms, total 2147ms, 6 deltas
model B: first token 10978ms, total 11010ms, 3 deltas

Model B's total is not ten times worse than A's; it simply thought for a long time before speaking. In the "buffer then print" implementation those eleven seconds are a completely silent black screen; with streaming, the user sees characters moving in the second second. Streaming is not a nicety, it is the only remedy for time to first token — and it is the first thing we build tomorrow.

In those two lines the delta count is reproducible (ask the same model the same question and the magnitude holds), and the timings are not (they depend on your network and the load at that moment), so read them only for the relative relationship.

Source Reading

• Anthropic: Building effective agents (the original argument for loops and tools): the first-hand source for the judgment that an Agent is a loop with tools. Today you only need its distinction between tool loops and workflows — twenty-one days here build the former, in a form where every layer can be replaced.
• OpenRouter docs: the OpenAI-compatible API and model id naming: compare the request body fields and the model id naming rules, and note that its model ids carry a vendor prefix.
• n1n docs: another OpenAI-compatible gateway, for comparing base URL and model id differences: read it side by side with the previous entry and you see the same endpoint and the same auth header with a different model id form — the practical basis for the rule that a model id must be configuration.

Hands-On Lab

1. Split input into two paths: slash commands go to the command table, everything else to conversation. Start the table with /help, /clear, /seed, /model and /exit.
2. Define the three type families — messages, tools, events — plus the gateway interface with its single streaming method. Define the tool types even though today does not use them: they are the foundation for the next twenty days, and they freeze once written.
3. Implement the gateway provider: hand-write the request body, take base URL, key and model id from the environment, and parse SSE into text deltas.
4. Implement the offline script provider so MOCK=1 sends no network requests and emits the same event sequence as the real path.
5. Write the self-test entry point: MOCK=1 SELFTEST=1 pnpm start prints a pass or fail per item, proving the sandbox repo, command routing, offline streaming and gateway switching all work.

Acceptance is four ticks: the self-test prints 4/4 passed; piping /help shows the command table; any question produces an answer with more than one delta; and changing two environment variables switches gateways.

Interview Questions

Today's three questions all test whether you have actually written one, not whether you know what an Agent is:

1. How would you split a terminal Coding Agent into layers? Which layer must a vendor SDK never leak into?
2. Vendors all provide official SDKs, so why write your own gateway abstraction? When does that layer become a burden?
3. For a command-line tool that depends heavily on a paid model API, how do you make development and testing possible without a key?

The full bilingual prompts, analyses and key points are in this course's day-one question bank. Questions two and three are the most frequently probed in this course — the first tests where an abstraction belongs, the second tests engineering habits, and both answers must land on concrete files rather than stopping at principles.

Checklist and Tomorrow

• I can draw the five layers and state each one's inputs, outputs and replacement cost
• I know why provider types must not enter the Agent Loop, and which layer the translation belongs to
• I can explain the roles of the three environment variables plus the offline switch
• The command table is data rather than an if-chain, and the parser splits without checking existence
• The offline script and the real gateway emit the same event sequence, including the trailing usage and finish reason
• The self-test entry point prints 4/4 passed, and I know why an exit code alone is not enough

Tomorrow is D2, "Streaming Output and Terminal Rendering: Hand-Written SSE Parsing, Incremental Markdown, and an Interruptible Typewriter": we dismantle today's buffer-then-print black screen. We write the SSE parser in its full form (framing by blank lines, handling half lines and stream interruptions), translate gateway deltas into semantic events, build incremental typewriter rendering in the terminal, and make it interruptible at any moment. Today's eleven silent seconds become characters moving in the second second.