Skip to main content

Mini Harness

A minimal Agent Harness core — the smallest complete implementation of an agent runtime. 1001 lines of Python. 49 tests. DeepSeek-first.

ReAct agent loop, streaming tool-call delta concatenation, 7-tool registry, 3-tier permission model, checkpoint/resume, step-level observability.

Demo

See demos/ — screenshots and HTML terminal replay covering all 5 features.

What is this?

The "brain + body" of an AI agent — the runtime shell that turns a raw LLM into a tool-using, permission-gated, controllable agent.

Does:

  • ReAct agent loop with streaming (think → act → observe → repeat)
  • 7 tools: read, write, edit, grep, glob, bash, fetch
  • Tool call delta concatenation (streamed arguments assembled by index)
  • 3-tier permission model (read / yn / auto) + hard-wall
  • Step trace: timing, token count, step counter per turn
  • Interrupt/Resume: Ctrl+C mid-run → rollback to checkpoint → continue/discard
  • Write verification: auto-read after write to prevent fake success

Does NOT:

  • Knowledge management, multi-agent, web dashboards, skill systems

Architecture

User Input
    │
    ▼
┌──────────────────────────────────────┐
│           Agent (loop.py)            │
│                                      │
│  save_checkpoint()                   │
│  async for delta in chat_stream():   │
│    yield text_delta  ← streaming     │
│    accumulate tool_call deltas       │
│  assemble response                   │
│  for each tool_call:                 │
│    permission gate ──────────────┐   │
│    execute handler (async)       │   │
│    result → messages ────────────┘   │
│  yield summary (steps/duration/tok)  │
└──────────────────────────────────────┘
    │            │               │
    ▼            ▼               ▼
┌─────────┐ ┌──────────┐ ┌──────────────┐
│ llm.py  │ │ tools.py │ │permissions.py│
│DeepSeek │ │ 7 tools  │ │ read/yn/auto │
│streaming│ │ unified  │ │ + hard-wall  │
│+ tokens │ │  async   │ │              │
└─────────┘ └──────────┘ └──────────────┘

Install

pip install mini-harness
# or dev:
pip install -e .

Quick Start

CLI

mini-harness

First run prompts for your DeepSeek API key (saved to ~/.mini-harness/config.toml).

> 列出当前目录的 Python 文件
  [1/15] glob · 0.8s · 45t
  [2/15] text · 0.3s · 89t
  — 2 steps · 1.1s · 134t
main.py
cli.py

Ctrl+C mid-run → [C]ontinue [D]iscard [Q]uit.

API

import asyncio
from harness import Agent, DeepSeekClient, Mode

async def main():
    client = DeepSeekClient(api_key="sk-...")
    agent = Agent(client, system_prompt="You are a helpful assistant.",
                  mode=Mode.AUTO)

    async for event in agent.run("List Python files in this project"):
        if event["type"] == "text_delta":
            print(event["text"], end="", flush=True)
        elif event["type"] == "tool_call":
            print(f"\n  [{event['step']}/{event['max_steps']}] {event['tool']}")
        elif event["type"] == "summary":
            print(f"\n  — {event['steps']} steps · "
                  f"{event['duration_ms']/1000:.1f}s · {event['tokens']}t")

asyncio.run(main())

Event Reference

Event Fields When
text_delta text Per-chunk during streaming
tool_call tool, params, step, max_steps, duration_ms, tokens Before tool execution
tool_result tool, success, output, step After tool execution
step_end step, kind, duration_ms, tokens Text-only responses
summary steps, duration_ms, tokens End of turn
interrupted step, message Ctrl+C caught
error message API failure, max steps

Permission Modes

Mode Read Write Bash Hard-wall bypass?
Read ✅ ❌ ❌ No
YN ✅ Prompt Prompt No
Auto ✅ ✅ ✅ No

Hard-wall (permanently blocked): rm -rf, sudo, git push --force, paths: raw/, agents/, archive/, /etc/, /proc/, /sys/.

Project Structure

mini-harness/
├── harness/
│   ├── __init__.py        # Public API
│   ├── cli.py             # REPL with interrupt dialog
│   ├── loop.py            # Agent Loop + streaming + checkpoint
│   ├── llm.py             # DeepSeek API (streaming + usage)
│   ├── tools.py           # 7 tools + registry + async handlers
│   └── permissions.py     # 3-tier + hard-wall
├── tests/                 # 49 tests
├── README.md
├── CHANGELOG.md
└── pyproject.toml

License

MIT

Metadata

Release files for mini-harness 1.0.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for mini-harness 1.0.1
File Size Uploaded Provenance Actions
mini_harness-1.0.1.tar.gz 19.6 kB Without provenance Details for mini_harness-1.0.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for mini-harness 1.0.1
File Interpreter ABI Platform Actions
mini_harness-1.0.1-py3-none-any.whl Python 3 none any Details for mini_harness-1.0.1-py3-none-any.whl

Total release size: 34.4 kB

Release files / mini_harness-1.0.1.tar.gz

Download URL mini_harness-1.0.1.tar.gz
Size 19.6 kB
Tags Source
SHA-256 checksum
How to use checksums
3a1ff0a9d6574a74bb0eca2e19063d7755065a4ed1f8df691012c19cefdcae61
BLAKE2b-256 checksum
How to use checksums
ee1482710a211e8185d54b7c4a0a3e40788c79db8701fd078485b517fa0c6549
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.12.10

Release files / mini_harness-1.0.1-py3-none-any.whl

Download URL mini_harness-1.0.1-py3-none-any.whl
Size 14.7 kB
Tags Python 3
SHA-256 checksum
How to use checksums
a08a64c884631905785a78b5ef0079440bc646804ea15e8e461dc74efd20b599
BLAKE2b-256 checksum
How to use checksums
e9b664ad6863e74224cf806ba320c61932df502a1a785035e915897c716a1fcb
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.12.10

Security for mini-harness 1.0.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

1.0.1 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page