Dependency-free · runs offline · Python 3.9+

Take an agent harness
apart, layer by layer.

A working agent harness in about 12,000 lines of Python, explained as a textbook: for every mechanism you get the concept, the failure it prevents, how this repository implements it, a command that proves it, and what it costs.

31textbook chapters
6parts, kernel to product
53feature flags
0core dependencies
Design stance

Most frameworks hide the interesting parts

MiniDSH optimizes for the opposite. Three rules make the whole harness inspectable — and make every failure explainable.

01

Services, not globals

Everything is a plugin that provides and requires named services. Disable a feature and its service, tool schema, and prompt section all disappear together — no special cases, no dead instructions.

02

Facts and projections are separate

The session log is append-only and immutable. What the model sees is a derived view that can be compacted, pruned, or replaced. The audit trail never shrinks.

03

Fail closed

Missing approver, unknown flag, corrupted session, missing preset, oversized payload — every one stops the operation with an explicit error instead of degrading silently.

Architecture

One composition root, three products

CLI, HTTP workbench, and Desktop share a single Application. Below it, every capability is a service resolved from the same context. The chapters follow this stack from the bottom up.

Products

minidsh CLI

run · resume · serve
sessions · surface · stream

minidsh-web

HTTP + SSE host
web/index.html workbench

minidsh-desktop

pywebview shell
optional dependency

▼
Composition

Application

app.py — the only assembly point

PluginManager

flags → dependency order
activate / deactivate

ServiceContext

one provider per name
optional resolution

▼
Runtime services

Agent loop

turn / step / tool call
cancellation · budget

Sessions

immutable generations
surface · compaction

Permissions

sandbox policy · approval
observations · seatbelt

Execution

jobs · PTY · subagents
workflow · run_code

Ecosystem

MCP · skills · presets
schedule · goals

▼
Model adapters

MockModel

deterministic · offline
EN + 中文 grammar

DeepSeek Messages

SSE · thinking replay
retry · images · Files API

Textbook

Every mechanism, one chapter

Each chapter has the same six blocks, so you can compare mechanisms directly: concept, why it exists, how it is implemented, how to verify it, what it costs, and where it sits in current practice.

Read in orderParts run kernel → runtime → safety → memory → collaboration → product. Later chapters assume the earlier ones.
Run as you readEvery “verify” block is copy-paste runnable offline. Commands are the same ones the CLI uses.
Compare with practiceEach chapter ends with the industry reference it maps to, so the lab and the standard can be read side by side.

Workbench

Watch the harness think

The local workbench renders a structured trace: model events, tool calls, approvals, file observations, and job lifecycle — with live streaming text, English/中文 switch, and light/dark themes.

MiniDSH workbench, light theme
Light theme · session history with approval and observation events
MiniDSH workbench, dark theme
Dark theme · the same session, same events
Quickstart

Offline in sixty seconds

No API key, no network, no third-party packages. The deterministic mock model makes every trajectory reproducible.

terminal
# clone and install (stdlib only)
git clone https://github.com/NorwinYu/dsh-python-lab.git
cd dsh-python-lab && python3 -m venv .venv && . .venv/bin/activate
python3 -m pip install -e .

# what does the model actually see?
minidsh plugins
minidsh tools
minidsh prompt

# run the offline agent
minidsh run "read README.md" --trace

# widen the policy, then approve the write
minidsh --sandbox-mode workspace-write --yes \
  run "write demo.txt: hello"

# open the workbench
minidsh serve --port 3080
# http://127.0.0.1:3080
01
No key required. The mock model maps explicit prefixes to tool intents. Chinese aliases exist too, so sessions can mix languages.
02
Read-only by default. Writes and shells need both a wider sandbox policy and an approval — two separate decisions on purpose.
03
Everything is inspectable. Sessions are JSONL generations. session, surface, and stream commands show raw events, the model view, and recorded chunks.
04
Real model is opt-in. Export DEEPSEEK_API_KEY, disable llm.mock, enable llm.deepseek. Keys are read from the environment only.
Boundaries

What it deliberately does not do

A lab that hides its limits is a demo. These are stated up front and tracked bullet by bullet in the parity report.

    Documentation

    Read, run, then take it apart

    English and Chinese guides, a module atlas, runnable labs, and an honest upstream parity report.