Module 1 — Foundations: What a Harness Is

A language model is a pure function. You hand it a sequence of tokens; it hands back a probability distribution over the next token, and then it forgets you existed. It cannot read your files, run your tests, remember yesterday, or stop itself halfway through a bad idea. Everything you experience when you use Claude Code, Codex CLI, or Cursor — the file it opened, the test it ran, the permission prompt it raised, the interrupt that actually interrupted — is code someone wrote around that pure function. That code is the agent harness. This module establishes what the harness is responsible for, what the model is responsible for, and where the boundary between them sits, because every later module in this course is a refinement of a boundary drawn here. By the end you will have built a crude but genuinely working harness in about 150 lines, and Modules 2 through 8 will spend the next 36 hours taking it apart.

Learning objectives

• M1.1 Define an agent harness and distinguish it from a model, an SDK, a chatbot, and an agent framework.
• M1.2 Explain statelessness: why every turn resends the full conversation, and what that implies for cost and latency.
• M1.3 Trace the anatomy of a request — system prompt, message history, tool schemas, sampling params — and the anatomy of a response, including streaming deltas and stop reasons.
• M1.4 Distinguish the harness's four standing responsibilities: composing context, executing effects, enforcing policy, and surviving failure.
• M1.5 Compare harness topologies — CLI, IDE extension, headless/CI, server/BFF, ACP-style automation — and what each constrains.
• M1.6 Read a harness's capability seam: where the model-agnostic core stops and the provider adapter begins.
• M1.7 Build a ~150-line working harness (read/write file + shell + loop) as the spine the rest of the course refactors.

Prerequisites and time

Prerequisites. Working TypeScript or Python. Comfort with async/await, JSON, and HTTP. You should have used an agentic coding tool; you are not assumed to have built one. No machine-learning background is required — this course treats the model as a component with a documented interface, not as a subject of study.

Estimated time. 4 hours: roughly 2.5 hours reading and 1.5 hours on the lab.

Setup for the lab. Node 20+ (for native fetch), and an API key for any OpenAI-compatible chat-completions endpoint. The spine you build in this module reads DEEPSEEK_API_KEY from the environment, plus optional DEEPSEEK_BASE_URL and DSH_MODEL — set both of those to point it at a provider other than DeepSeek. It does not read a .env file. Never commit a key.

Setup for reading along. The worked examples quote the reference implementation, DeepSeek Harness (dsh), by file and line. Clone it at the commit the course was checked against, so the line numbers match:

git clone https://github.com/Hilo-Inc/deepseek-harness.git
cd deepseek-harness
git checkout b150a551b8d465e31e418e1b2eaf5e79bbb7d28e

Unless a path is marked otherwise, every repository path in this course — AGENTS.md, docs/…, packages/… — is relative to the root of that checkout, not to the course repository. Later versions of dsh will have moved lines and may have changed behaviour; if a citation does not match, check your commit first.