DEV Community: Charlie Hu

A Scope Card Beats a Bigger Prompt: Cutting a Weekend Agent Demo to One Path

Charlie Hu — Thu, 24 Sep 2026 21:34:20 +0000

A weekend agent demo is finished when one named path returns a checked result. A larger prompt does not finish it. Free model access and a free server option lower the cost of a trial, and they leave the failure mode unchanged: the side project dies in unfinished scope.

Disclosure: This article was prepared as part of MonkeyCode's product outreach. The only product claims used here are operator-supplied: free model access and a free server option. Model names, token quotas, hardware, duration, and permanence are omitted because they were not verified for this draft. Current docs should be checked before either option is treated as a fixed budget.

The public posts on this account already cover small controls around agent side projects: merge gates, tool allowlists, call envelopes, circuit breakers, dry-run staging, and worker heartbeats. This note does not rebuild those controls. It covers the cut that has to happen before any of them earn a place in a two-day repo. The audience is a developer shipping a narrow demo, not a team designing a platform.

Cut first, then host

The working demo is a local command. It reads a scope card, accepts one intent, and prints a fixture result plus an explicit skip ledger. A live call stays behind a flag that defaults to off.

A free server can host that same process later. It is not required to prove the slice. Saturday defines the card. Sunday runs the fixture path and writes down what was refused.

Anything that needs a model token is a follow-up slice, and only if the fixture cannot show the response shape honestly. That order is the method. Hosting is a later convenience, not the proof.

Scope card

The card is JSON so the draft runner has no parser dependency. Field names stay blunt on purpose. A reader should see the cut without a diagram.

{
  "slice_id": "invoice-status-v0",
  "allowed_intents": ["lookup_invoice_status"],
  "fixture": {
    "tool": "billing.lookup",
    "input": {"invoice_id": "INV-1042"},
    "output": {"status": "open", "currency": "USD", "amount_cents": 4200}
  },
  "skipped": [
    "multi-invoice search",
    "refunds and other writes",
    "a browser UI",
    "retries, workers, and cron",
    "a second model call to explain the status"
  ],
  "live": {
    "enabled_by_default": false,
    "env_base_url": "AGENT_SLICE_BASE_URL",
    "path": "/v0/slice",
    "timeout_seconds": 10
  }
}

slice_id names the demo. allowed_intents is a closed set. fixture is the result a reviewer can rerun without an account. skipped is the scope cut, stored as data so it shows up in the command output.

live records how a later call would be addressed. The path /v0/slice is a local contract for this side project. It is not a documented vendor endpoint, and it should not be copied into a client as if it were one.

Runner

The module below is a proposal. It has not been timed, load-tested, or pointed at a hosted offer. It refuses unknown intents before any network call. It replays the fixture unless --live is set. It prints the skip list on every exit path so a green demo cannot hide the cut.

#!/usr/bin/env python3
"""Unexecuted proposal: one-intent scope runner for a weekend demo."""

from __future__ import annotations

import argparse
import json
import os
import sys
import urllib.error
import urllib.request
from pathlib import Path


def load_card(path: Path) -> dict:
    try:
        card = json.loads(path.read_text(encoding="utf-8"))
    except json.JSONDecodeError as exc:
        raise SystemExit(f"card_not_json: {exc}") from exc
    for key in ("slice_id", "allowed_intents", "fixture", "skipped", "live"):
        if key not in card:
            raise SystemExit(f"card_missing_field: {key}")
    if not isinstance(card["allowed_intents"], list) or not card["allowed_intents"]:
        raise SystemExit("card_needs_one_intent")
    return card


def decide(card: dict, intent: str, live: bool) -> dict:
    skipped = list(card.get("skipped") or [])
    allowed = set(card["allowed_intents"])
    if intent not in allowed:
        return {
            "ok": False,
            "slice_id": card["slice_id"],
            "reason": "intent_outside_slice",
            "skipped": skipped,
        }
    if not live:
        return {
            "ok": True,
            "slice_id": card["slice_id"],
            "mode": "fixture",
            "result": card["fixture"]["output"],
            "skipped": skipped,
        }
    env_name = card["live"]["env_base_url"]
    base = os.environ.get(env_name, "").rstrip("/")
    if not base:
        return {
            "ok": False,
            "slice_id": card["slice_id"],
            "reason": "live_requested_but_base_url_missing",
            "skipped": skipped,
        }
    payload = json.dumps(
        {
            "slice_id": card["slice_id"],
            "intent": intent,
            "input": card["fixture"]["input"],
        }
    ).encode("utf-8")
    timeout = int(card["live"].get("timeout_seconds", 10))
    req = urllib.request.Request(
        base + card["live"]["path"],
        data=payload,
        headers={"content-type": "application/json"},
        method="POST",
    )
    try:
        with urllib.request.urlopen(req, timeout=timeout) as resp:
            body = json.loads(resp.read().decode("utf-8"))
    except (urllib.error.URLError, TimeoutError, json.JSONDecodeError) as exc:
        return {
            "ok": False,
            "slice_id": card["slice_id"],
            "reason": "live_call_failed",
            "detail": type(exc).__name__,
            "skipped": skipped,
        }
    return {
        "ok": True,
        "slice_id": card["slice_id"],
        "mode": "live",
        "result": body,
        "skipped": skipped,
    }


def main() -> int:
    parser = argparse.ArgumentParser(description="Run one scoped demo path")
    parser.add_argument("--card", required=True)
    parser.add_argument("--intent", required=True)
    parser.add_argument("--live", action="store_true")
    args = parser.parse_args()
    report = decide(load_card(Path(args.card)), args.intent, args.live)
    json.dump(report, sys.stdout, indent=2)
    sys.stdout.write("\n")
    return 0 if report.get("ok") else 2


if __name__ == "__main__":
    raise SystemExit(main())

Two behaviors are deliberate. The live failure returns an error type, not the exception text, so a URL or upstream body is less likely to land in a pasted demo log. The fixture path never reads AGENT_SLICE_BASE_URL.

A configured host cannot change the default demo. That split is what makes the weekend rerunnable after a laptop reboot, with or without a network.

Commands and expected reports

Save the card as scope.invoice.json and the module as slice_runner.py. Then run the dry path:

python3 slice_runner.py \
  --card scope.invoice.json \
  --intent lookup_invoice_status

The expected report shape is:

{
  "ok": true,
  "slice_id": "invoice-status-v0",
  "mode": "fixture",
  "result": {"status": "open", "currency": "USD", "amount_cents": 4200},
  "skipped": ["multi-invoice search", "refunds and other writes"]
}

An intent outside the card must fail closed, with no socket:

python3 slice_runner.py \
  --card scope.invoice.json \
  --intent refund_invoice
echo "exit=$?"

reason should be intent_outside_slice, and the exit code should be 2. The skip list should still print. A reviewer who asks for refunds gets a recorded refusal, not a silent success.

Requesting a live call without the env var is the third check:

python3 slice_runner.py \
  --card scope.invoice.json \
  --intent lookup_invoice_status \
  --live

Expected reason: live_requested_but_base_url_missing. The runner must not guess a host, and it must not fall back to the fixture while claiming a live result. Those are different failures. Mixing them makes the demo look healthier than the setup is.

Decision table

Weekend pressure	Keep in v0	Replace with the fixture	Write into `skipped`
Add one more intent	Only if the sentence still names one path	—	The extra intent
Show a model answer	Only for a field the fixture cannot shape	Status, amount, currency	Explanations and chat
Put it on a server	One process, one route, after the local command works	A checked-in JSON file	Queues and background jobs
Make it look finished	The skip list in the output	—	A UI that hides skips
Handle failure	Non-zero exit and a reason code	—	Retries and backoff trees

Use the table as a review checklist, not as a slogan. If a row cannot be filled without inventing a metric, the row stays blank and the work stays skipped.

Where a free route actually helps

Free model access is relevant on the step a fixture would fake. In this invoice slice, that step does not exist yet. Status, currency, and amount are canned. A later card might allow one intent, classify_invoice_note, whose input is a short ambiguous string and whose output is a label plus a reason code.

That is the first honest use of a model. It is still one request, still checked against allowed_intents, and still off unless --live is passed. A free server option is relevant after that local command is boring.

Copy the same three files to the host, set the base URL only for the live flag, and keep the fixture command as the regression check. Region, size, and how long the offer lasts are not known here. If the host is unavailable on demo day, the fixture path still runs on a laptop. That fallback is the reason the card exists.

Do not treat either option as a capacity plan. This draft measured nothing: no latency, no token count, no concurrency. A number copied from an older post would be worse than a blank. Confirm the current terms in the product docs before spending a weekend on a live flag.

What the weekend skips

The skip list is the build log. It is not a backlog disguised as humility.

No planner loop. One intent in, one result out. Turn caps belong to a different note.
No tool bus. The fixture names one tool string. It does not route, stage, or allowlist a catalog.
No receipt book and no heartbeat. Those mechanisms answer other questions. Pulling them in would erase the cut.
No write path. Refunds stay skipped because a demo mutation is how a side project stops being a demo.
No second model call to explain the status. Explanation text is how scope leaks back in.
No claim about a token pool, a machine size, or an end date. Unverified numbers stay out of the README as well as this page.

Failure notes worth keeping

A few failures are more instructive than the happy path.

A card with an empty allowed_intents list should exit on load. A slice that allows everything is not a slice.
A live timeout should surface as live_call_failed with detail set to the exception type. The demo script can then say the host did not answer, which is a true statement.
A fixture output that omits a field the reviewer expects should be fixed in the card, not patched in the runner. Hidden defaults recreate the unfinished product.
Editing skipped without editing the spoken demo is a process bug. The command output is the script.

Clear field names do more work here than a comment. If skipped needs a paragraph to explain itself, the cut is still fuzzy and the card is not ready to demo.

Test plan before calling it a demo

These checks are local and manual until they are pasted into a real file and run. Until then they are a plan, not a result.

Parse failure: truncate the JSON and confirm a non-zero exit with card_not_json.
Missing field: delete skipped and confirm card_missing_field.
Fixture path: allowed intent, no --live, result equals fixture.output.
Reject path: unknown intent, no socket, exit code 2.
Live guard: --live and an empty base URL, no guessed host, no fixture fallback.
Skip visibility: every string in skipped appears in the report for both success and refusal.
Timeout lock: timeout_seconds stays at 10. A hung process must not become the demo.

A single assertion can lock check 3 once the function is imported:

def test_fixture_path():
    card = {
        "slice_id": "invoice-status-v0",
        "allowed_intents": ["lookup_invoice_status"],
        "fixture": {"output": {"status": "open"}},
        "skipped": ["refunds and other writes"],
        "live": {"env_base_url": "AGENT_SLICE_BASE_URL", "path": "/v0/slice"},
    }
    report = decide(card, "lookup_invoice_status", live=False)
    assert report["mode"] == "fixture"
    assert report["result"]["status"] == "open"
    assert report["skipped"] == ["refunds and other writes"]

Run it only after the file exists in the repo. A pasted assertion is not a passing suite. Record the command and the exit code in the README next to the skip list, so the next session does not have to reconstruct the demo from memory.

Who should not use this

This runner is a scope fence for a side project. It is not authentication, not authorization, and not a sandbox. A person who can edit the card can widen the slice. A person who can set the base URL can send the payload to an unintended host.

Skip the approach when any of these are true:

The demo must mutate real billing data or other customer state.
A reviewer has already been promised several intents. Cut the promise before writing code.
The audience needs a latency, cost, or uptime figure. None were measured.
The host must stay up unattended. This draft does not establish that.
Secrets need more care than one env var that is never printed. The example does not redact arbitrary logs.
The work is a multi-tenant product. A JSON card in a repo root is the wrong boundary.

Clear fields beat a cleaner abstraction that hides the skip list. If a comment is required to explain skipped, the field name is wrong, not the reader.

After the card is boring

Leave the card in the repo root. Add a second intent only by copying the card to a new slice_id and deleting the old promises from the spoken demo. If a free model route and a free server are still available for that next slice, spend them on the one step the fixture cannot show, and confirm the current terms before relying on either. The weekend result is the cut. A longer catalog can wait.

Stamp the Run: A Weekend Receipt Book for Agent Side Projects

Charlie Hu — Wed, 23 Sep 2026 17:16:49 +0000

Weekend agent loops fail in the dark. Tools fire, files change, and the process exits with no record of why. A receipt book — one JSON file per run — is the smallest Saturday-scoped fix that still leaves a working demo.

This write-up is a labeled weekend build log, not a production tracing guide. The code is a self-contained example. It records stop reasons, tool names, and touched paths. It does not replay raw model traffic.

Scope cut for one weekend

In scope:

A frozen receipt schema on disk
A tiny Python store with open, record_tool, record_file, and close
A CLI an agent loop can shell out to
Tests that fail if a run ends without a stop reason

Skipped on purpose:

Provider token invoices and live cost dashboards
OpenTelemetry and distributed trace graphs
Encryption at rest and multi-user auth
Concurrent writers and an HTTP API

The cut is the product. A receipt that always closes beats a half-finished observability stack.

The receipt schema

Each run writes receipts/<run_id>.json. Fields earn their keep or they stay out.

{
  "run_id": "9f3c1a2e-6b44-4d1a-9c0e-0c7b2d8a1111",
  "started_at": "2026-09-23T10:00:00+00:00",
  "ended_at": null,
  "status": "open",
  "stop_reason": null,
  "tool_calls": [],
  "files_touched": [],
  "call_count": 0,
  "notes": []
}

Rules that keep the file greppable:

status is only open or closed.
close refuses to write when stop_reason is missing.
Tool records store a name, ok/error, and a 200-character detail cap.
File records store a path, an action (read | write | delete), and a dry_run flag.
call_count is a local increment, not a vendor bill.

A cassette records raw model I/O for replay. This receipt is the opposite: a human summary that is safe to commit, grep, and diff.

Working demo: the store

Label: example code, not a published package. Python 3.11+ and the standard library are enough.

# receipt_book.py
from __future__ import annotations

import argparse
import json
import uuid
from datetime import datetime, timezone
from pathlib import Path
from typing import Any, Literal

ROOT = Path("receipts")
DETAIL_CAP = 200
StopReason = Literal["success", "max_turns", "tool_error", "user_abort", "unknown"]
FileAction = Literal["read", "write", "delete"]


def _now() -> str:
    return datetime.now(timezone.utc).isoformat()


def _path(run_id: str) -> Path:
    ROOT.mkdir(parents=True, exist_ok=True)
    return ROOT / f"{run_id}.json"


def _load(run_id: str) -> dict[str, Any]:
    path = _path(run_id)
    if not path.exists():
        raise FileNotFoundError(f"no receipt for {run_id}")
    return json.loads(path.read_text(encoding="utf-8"))


def _save(doc: dict[str, Any]) -> None:
    path = _path(doc["run_id"])
    tmp = path.with_suffix(".json.tmp")
    tmp.write_text(json.dumps(doc, indent=2, sort_keys=True) + "\n", encoding="utf-8")
    tmp.replace(path)


def open_run() -> str:
    run_id = str(uuid.uuid4())
    _save(
        {
            "run_id": run_id,
            "started_at": _now(),
            "ended_at": None,
            "status": "open",
            "stop_reason": None,
            "tool_calls": [],
            "files_touched": [],
            "call_count": 0,
            "notes": [],
        }
    )
    return run_id


def record_tool(run_id: str, name: str, ok: bool, detail: str = "") -> None:
    doc = _load(run_id)
    if doc["status"] != "open":
        raise RuntimeError("cannot record on a closed receipt")
    doc["tool_calls"].append(
        {"name": name, "ok": ok, "detail": detail[:DETAIL_CAP], "at": _now()}
    )
    doc["call_count"] += 1
    _save(doc)


def record_file(run_id: str, path: str, action: FileAction, dry_run: bool) -> None:
    doc = _load(run_id)
    if doc["status"] != "open":
        raise RuntimeError("cannot record on a closed receipt")
    doc["files_touched"].append(
        {"path": path, "action": action, "dry_run": dry_run, "at": _now()}
    )
    _save(doc)


def close_run(run_id: str, stop_reason: StopReason) -> dict[str, Any]:
    doc = _load(run_id)
    if doc["status"] == "closed":
        return doc
    if not stop_reason:
        raise ValueError("stop_reason is required")
    doc["status"] = "closed"
    doc["stop_reason"] = stop_reason
    doc["ended_at"] = _now()
    _save(doc)
    return doc


def main() -> None:
    parser = argparse.ArgumentParser(prog="receipt")
    sub = parser.add_subparsers(dest="cmd", required=True)
    sub.add_parser("open")
    p_tool = sub.add_parser("tool")
    p_tool.add_argument("run_id")
    p_tool.add_argument("name")
    p_tool.add_argument("--ok", action="store_true")
    p_tool.add_argument("--detail", default="")
    p_file = sub.add_parser("file")
    p_file.add_argument("run_id")
    p_file.add_argument("path")
    p_file.add_argument("action", choices=["read", "write", "delete"])
    p_file.add_argument("--dry-run", action="store_true")
    p_close = sub.add_parser("close")
    p_close.add_argument("run_id")
    p_close.add_argument(
        "stop_reason",
        choices=["success", "max_turns", "tool_error", "user_abort", "unknown"],
    )
    args = parser.parse_args()
    if args.cmd == "open":
        print(open_run())
    elif args.cmd == "tool":
        record_tool(args.run_id, args.name, args.ok, args.detail)
    elif args.cmd == "file":
        record_file(args.run_id, args.path, args.action, args.dry_run)
    elif args.cmd == "close":
        close_run(args.run_id, args.stop_reason)


if __name__ == "__main__":
    main()

Atomic replace through a .tmp file is the whole durability story. A crash mid-write should not leave half a JSON object.

Saturday commands look like this:

RUN_ID=$(python receipt_book.py open)
python receipt_book.py tool "$RUN_ID" list_dir --ok --detail "src/"
python receipt_book.py file "$RUN_ID" src/app.py write --dry-run
python receipt_book.py close "$RUN_ID" success
cat "receipts/${RUN_ID}.json"

A one-liner then lists every run on Sunday morning:

python - <<'PY'
import json
from pathlib import Path
for p in sorted(Path("receipts").glob("*.json")):
    doc = json.loads(p.read_text())
    print(
        f"{doc['run_id'][:8]} {doc['status']:6} {doc['stop_reason']!s:10} "
        f"calls={doc['call_count']} files={len(doc['files_touched'])}"
    )
PY

Open rows are the ones that died without close. That grep is the debugging workflow.

Wiring a toy agent loop

Label: example loop. The planner is a stub. Swap it for any local or remote model client without touching the receipt schema.

# toy_loop.py
from receipt_book import close_run, open_run, record_file, record_tool

MAX_TURNS = 4
ALLOWED = {"list_dir", "read_file", "dry_write"}


def planner(turn: int) -> dict:
    # Placeholder planner. Real loops call a model here.
    if turn == 0:
        return {"tool": "list_dir", "arg": "src"}
    if turn == 1:
        return {"tool": "dry_write", "arg": "src/app.py"}
    return {"tool": "stop", "arg": "success"}


def run() -> str:
    run_id = open_run()
    try:
        for turn in range(MAX_TURNS):
            step = planner(turn)
            name = step["tool"]
            if name == "stop":
                close_run(run_id, "success")
                return run_id
            if name not in ALLOWED:
                record_tool(run_id, name, False, "blocked")
                close_run(run_id, "tool_error")
                return run_id
            record_tool(run_id, name, True, step["arg"])
            if name == "dry_write":
                record_file(run_id, step["arg"], "write", dry_run=True)
        close_run(run_id, "max_turns")
        return run_id
    except Exception as exc:
        record_tool(run_id, "loop", False, str(exc))
        close_run(run_id, "unknown")
        raise


if __name__ == "__main__":
    print(run())

The loop always closes. Exceptions still write unknown. That is the entire reliability claim for the weekend.

Tests that fail closed

# test_receipt_book.py
from pathlib import Path

import pytest

import receipt_book as rb


def test_close_requires_stop_reason(tmp_path, monkeypatch):
    monkeypatch.setattr(rb, "ROOT", tmp_path)
    run_id = rb.open_run()
    with pytest.raises(ValueError):
        rb.close_run(run_id, "")  # type: ignore[arg-type]


def test_records_then_closes(tmp_path, monkeypatch):
    monkeypatch.setattr(rb, "ROOT", tmp_path)
    run_id = rb.open_run()
    rb.record_tool(run_id, "list_dir", True, "src")
    rb.record_file(run_id, "src/app.py", "write", True)
    doc = rb.close_run(run_id, "success")
    assert doc["status"] == "closed"
    assert doc["call_count"] == 1
    assert Path(tmp_path, f"{run_id}.json").exists()


def test_no_writes_after_close(tmp_path, monkeypatch):
    monkeypatch.setattr(rb, "ROOT", tmp_path)
    run_id = rb.open_run()
    rb.close_run(run_id, "user_abort")
    with pytest.raises(RuntimeError):
        rb.record_tool(run_id, "list_dir", True, "")


def test_dry_write_leaves_a_file_row(tmp_path, monkeypatch):
    monkeypatch.setattr(rb, "ROOT", tmp_path)
    run_id = rb.open_run()
    rb.record_tool(run_id, "dry_write", True, "src/app.py")
    rb.record_file(run_id, "src/app.py", "write", True)
    doc = rb.close_run(run_id, "success")
    assert doc["files_touched"][0]["dry_run"] is True

pytest -q test_receipt_book.py

A missing stop reason is a failed test, not a log line someone might notice later. The last test encodes an invariant: a dry_write tool call should leave a file row, or the receipt is lying.

Decision table: stamp vs skip

Event	Stamp on the receipt	Skip this weekend
Tool name and ok/error	Yes	Full stdout dumps
File path and action	Yes	File contents
Stop reason	Yes	Secret-bearing stack traces
Local call count	Yes	Vendor token invoices
Raw model prompt	No	Cassette / replay fixtures

The table is the scope cut in one place. If a field is not in the left column, it does not ship before Monday.

Failure analysis from a dry run

Three failure shapes show up in side-project agent loops. The receipt book only helps if each shape maps to a row.

Process killed. kill -9 after _save of an open receipt leaves status=open and ended_at=null. Sunday's listing command surfaces those files. Manual close with unknown is allowed; the CLI will not invent a success.
Planner returns an unknown tool. The loop records ok=false, detail blocked, then closes with tool_error. The allowlist stays in the loop, not in the receipt schema.
Dry-write never recorded. tool_calls contains dry_write while files_touched is empty. That mismatch is a bug in the loop, not in the model. The fourth test above is there to catch it.

None of those cases need a trace backend. They need a file that still exists after the shell is gone.

Where a free remote planner fits

Local loops still need a planner when the weekend machine should not host a large model. A remote coding assistant can return the next tool name. The receipt file stays on disk beside the repo.

Disclosure: This article was prepared as part of MonkeyCode's product outreach.

MonkeyCode offers free model access and a free server option. Those two properties matter here for one reason: the planner can live off-laptop while the receipt file, allowlisted tools, and dry-run writes stay local. The schema does not depend on that product. A different remote endpoint works the same way. This account's relationship is product outreach, not an independent benchmark lab.

A practical split for the same weekend constraint:

Keep receipt_book.py and the tool allowlist on the laptop.
Send the planner only a short state card: last tool, last error, remaining turns.
Write whatever the planner returns onto the receipt before executing it.
Close the receipt even if the remote call fails.

Free remote capacity is optional fuel, not the architecture. The receipt still closes if the network does not.

What this weekend skipped

No token accounting against a vendor bill. call_count is a local counter. No redaction beyond the 200-character cap, so secrets can still leak through detail. No concurrent writers: two processes sharing one run_id can clobber records. No HTTP surface and no UI. The CLI is the API. cat is the UI.

Skipping those items is how the demo stays runnable before Monday. Adding any one of them usually consumes the rest of the weekend.

Limitations

The store is a JSON file. It is not a ledger. Clock skew, a kill after the .tmp write but before replace, and copied receipts across machines are all unhandled. Detail truncation hides the exact error that mattered. Call counts are not money.

The toy planner is a stub. It does not prove model quality, latency, or safety. Dry-run flags are advisory. A loop that ignores dry_run=True will still write to disk.

Who should not use this approach

Teams that already emit structured traces for every tool call
Agents that write production data or customer files
Anyone who needs a legally complete audit log
Multi-tenant services
Workflows that treat a receipt as authorization to re-run destructive tools

Those cases need a sandbox, a real allowlist, and an observability pipeline. A closed JSON receipt will not make an agent safe. It will make Sunday debugging shorter. That is the only claim this weekend build makes.

Stage the Tools: A Weekend Dry-Run Bus for Agent Side Projects

Charlie Hu — Tue, 22 Sep 2026 15:29:02 +0000

Weekend agent side projects usually fail at the tool boundary, not inside the prompt. A model proposes a call, the host runs it, and a missing key or a second retry writes to the wrong path. A dry-run bus records the intended call, checks a tiny contract, and forwards only after that check passes.

This article is a scoped weekend build log for that bus. The working demo is one Python module, a JSONL ticket log, and a short test file. Distributed queues, vendor lock-in, and production tracing were left on the floor.

The problem the bus is for

Side-project agents tend to grow a single run_tool(name, args) function. That function talks to the filesystem, the network, or a shell. It is convenient. It is also how a sloppy loop mutates local state before anyone reads the trace.

Tool-calling tutorials often jump straight to a live API. That is the wrong first step for a Saturday project. The first step is a ticket. Every proposed call becomes a row that can be inspected, rejected, or released.

A dry-run bus sits in front of execution. Live model traffic stays optional until the tickets look honest.

Weekend scope that survived the cut

The build kept three jobs. Everything else was treated as next-month work.

Kept

A JSONL ticket log on disk, one object per line.
A per-tool contract for required keys and simple JSON types.
A live adapter that stays off unless an environment flag is set.

Cut on purpose

Redis, Kafka, or any networked queue.
OpenTelemetry exporters and flame graphs.
Prompt assembly, memory, and retrieval.
Automatic dollar forecasts or vendor price tables.
Multi-user auth.

The goal is a demo that runs before Sunday night. A platform can wait.

Artifact: a ticketed tool bus

The following module is a proposed weekend sketch. It is labeled as unexecuted design until the tests below are run on a local machine. Save it as toolbus.py.

from __future__ import annotations

import json
import os
import time
import uuid
from dataclasses import asdict, dataclass, field
from pathlib import Path
from typing import Any, Callable, Mapping

Json = dict[str, Any]
LiveFn = Callable[[str, Json], Json]

CONTRACTS: dict[str, dict[str, type]] = {
    "read_file": {"path": str},
    "write_file": {"path": str, "contents": str},
    "http_get": {"url": str},
}

FORBIDDEN_KEYS = {"api_key", "token", "password", "authorization"}


@dataclass
class Ticket:
    ticket_id: str
    tool: str
    args: Json
    status: str
    reason: str = ""
    ts: float = field(default_factory=time.time)

    def row(self) -> Json:
        return asdict(self)


class ContractError(ValueError):
    pass


def validate(tool: str, args: Mapping[str, Any]) -> None:
    spec = CONTRACTS.get(tool)
    if spec is None:
        raise ContractError(f"unknown tool: {tool}")
    missing = [k for k in spec if k not in args]
    if missing:
        raise ContractError(f"missing keys: {missing}")
    for key, expected in spec.items():
        if not isinstance(args[key], expected):
            raise ContractError(f"{key} expected {expected.__name__}")
    leaked = FORBIDDEN_KEYS.intersection(args):
    if leaked:
        raise ContractError(f"forbidden keys: {sorted(leaked)}")
    if tool == "http_get":
        url = str(args["url"])
        if not url.startswith(("https://", "http://127.0.0.1", "http://localhost")):
            raise ContractError("url scheme not allowed")
    if tool in {"read_file", "write_file"}:
        path = Path(str(args["path"])).resolve()
        root = Path.cwd().resolve()
        if root not in path.parents and path != root:
            raise ContractError("path escapes workspace")


class ToolBus:
    def __init__(self, ledger: Path, live: LiveFn | None = None) -> None:
        self.ledger = ledger
        self.live = live
        self.ledger.parent.mkdir(parents=True, exist_ok=True)
        self.ledger.touch(exist_ok=True)

    def _append(self, ticket: Ticket) -> None:
        with self.ledger.open("a", encoding="utf-8") as handle:
            handle.write(json.dumps(ticket.row(), ensure_ascii=True) + "\n")

    def stage(self, tool: str, args: Json, *, execute: bool = False) -> Ticket:
        ticket_id = uuid.uuid4().hex[:12]
        try:
            validate(tool, args)
        except ContractError as exc:
            ticket = Ticket(ticket_id, tool, dict(args), "rejected", str(exc))
            self._append(ticket)
            return ticket

        if not execute:
            ticket = Ticket(ticket_id, tool, dict(args), "staged", "dry-run")
            self._append(ticket)
            return ticket

        if self.live is None:
            ticket = Ticket(ticket_id, tool, dict(args), "blocked", "no live adapter")
            self._append(ticket)
            return ticket

        result = self.live(tool, dict(args))
        ticket = Ticket(
            ticket_id,
            tool,
            {"args": dict(args), "result_keys": sorted(result)},
            "executed",
            "live",
        )
        self._append(ticket)
        return ticket

    def pending(self) -> list[Json]:
        rows: list[Json] = []
        for line in self.ledger.read_text(encoding="utf-8").splitlines():
            if not line.strip():
                continue
            row = json.loads(line)
            if row.get("status") == "staged":
                rows.append(row)
        return rows

The bus never executes on stage() unless execute=True. That is the whole weekend trick. Staging is cheap. Execution is a separate, explicit act.

A live adapter can be a local function. It can also be a small HTTP client pointed at an environment URL. The bus does not care. The ledger does.

import json
import urllib.request


def http_live(tool: str, args: dict) -> dict:
    url = os.environ["TOOLBUS_LIVE_URL"]
    payload = json.dumps({"tool": tool, "args": args}).encode("utf-8")
    req = urllib.request.Request(
        url,
        data=payload,
        headers={"Content-Type": "application/json"},
        method="POST",
    )
    with urllib.request.urlopen(req, timeout=10) as resp:
        return json.loads(resp.read().decode("utf-8"))

Leave TOOLBUS_LIVE_URL unset during the first evening. The dry-run path still writes tickets. That is enough to review a loop without spending a model call.

Working demo

Create a scratch folder and install nothing beyond the Python standard library.

mkdir -p /tmp/toolbus-demo && cd /tmp/toolbus-demo
cat > toolbus.py <<'PY'
# paste the module above
PY

A tiny driver shows the three ticket states: rejected, staged, and blocked.

# save as demo.py
from pathlib import Path
from toolbus import ToolBus

bus = ToolBus(Path("tickets.jsonl"))

print(bus.stage("wipe_disk", {"path": "/"}).status)
print(bus.stage("read_file", {"path": "README.md"}).status)
print(bus.stage("read_file", {"path": "README.md"}, execute=True).status)
print(len(bus.pending()))

printf '# demo\n' > README.md
python demo.py
cat tickets.jsonl

Expected shape of the log, not a measured benchmark:

wipe_disk lands as rejected with unknown tool.
The first read_file lands as staged.
The second read_file lands as blocked because no live adapter was wired.
pending() returns the staged row only.

That output is the demo. A reader can screenshot the JSONL file and stop. The live lane is optional homework.

Tests that prove the cut is honest

Save the following as test_toolbus.py. The tests pin behavior, not performance.

from pathlib import Path

from toolbus import ToolBus


def test_unknown_tool_is_rejected(tmp_path: Path) -> None:
    bus = ToolBus(tmp_path / "t.jsonl")
    ticket = bus.stage("shell", {"cmd": "ls"})
    assert ticket.status == "rejected"


def test_path_escape_is_rejected(tmp_path: Path) -> None:
    bus = ToolBus(tmp_path / "t.jsonl")
    ticket = bus.stage("write_file", {"path": "../out.txt", "contents": "x"})
    assert ticket.status == "rejected"


def test_dry_run_does_not_call_live(tmp_path: Path) -> None:
    calls: list[str] = []

    def live(tool: str, args: dict) -> dict:
        calls.append(tool)
        return {"ok": True}

    bus = ToolBus(tmp_path / "t.jsonl", live=live)
    ticket = bus.stage("http_get", {"url": "http://127.0.0.1:9/health"})
    assert ticket.status == "staged"
    assert calls == []


def test_execute_uses_live_adapter(tmp_path: Path) -> None:
    def live(tool: str, args: dict) -> dict:
        return {"status": 200, "tool": tool}

    bus = ToolBus(tmp_path / "t.jsonl", live=live)
    ticket = bus.stage(
        "http_get",
        {"url": "http://127.0.0.1:9/health"},
        execute=True,
    )
    assert ticket.status == "executed"

pip install pytest
pytest -q test_toolbus.py

If those four tests pass, the weekend scope is done. Extra assertions about latency or token counts were not part of the cut.

Decision table for dry-run versus live

Use the table as a gate, not as a slogan.

Signal on the ticket	Action	Why
Unknown tool name	Reject	The allow-set is the contract.
Missing or mistyped args	Reject	Live models invent keys.
Forbidden secret-shaped keys	Reject	Tickets are logged in plaintext JSONL.
Path outside the workspace	Reject	Side projects live in one folder.
Contract ok, `execute=False`	Stage	Human or test review still pending.
Contract ok, no live adapter	Block	Fail closed.
Contract ok, live adapter set	Execute	Only this row may touch the network.

The table is the product of the weekend. The Python is just a way to enforce it.

Where a free model lane belongs

Disclosure: This article was prepared as part of MonkeyCode's product outreach.

The bus does not require a hosted model. A free model lane becomes useful only after pending() looks boring: same tools, same keys, no escaped paths. At that point a live adapter can point at a remote endpoint. MonkeyCode's free model access and free server option can host that live lane so the laptop is not both the agent and the dummy API. The bus, the ledger, and the tests stay local.

Do not put secrets in tickets. Do not treat a free lane as a production SLA. The adapter above is a weekend stub with a ten-second timeout and no retries.

What this weekend skipped

Several tempting features were written on a sticky note and then ignored.

Replay of staged tickets into a real filesystem write. Replay needs a second review step.
Canonical JSON hashing for cache hits. Hashing is a different article.
Streaming model output. The bus only sees completed tool argument objects.
Redaction of values already inside file contents. The forbidden-key check is shallow.
A web UI for the JSONL file. cat is enough for one developer.

Skipping those items is the difference between a demo and a half-finished platform. The demo is the point.

Limitations and who should not use this

The contract table is tiny. It understands str and a couple of path rules. Nested objects, arrays, and vendor-specific tool schemas are out of scope. The ledger is append-only plaintext. Anyone with disk access can read every staged URL and path.

This approach is a poor fit for:

Multi-tenant agents that handle other people's data.
Workloads that need an audit log with integrity protection.
Tools that must run with real credentials on the first call.
Long-running workers that already have a queue and a poison-letter policy.

Those projects need a real workflow engine. A weekend JSONL file will lie to them.

The live HTTP helper also has no backoff, no idempotency key, and no TLS pinning beyond what the Python runtime provides. Treat it as a teaching adapter. Replace it before any shared environment sees traffic.

Closing

Stage the tools first. Execute later. A Sunday-night side project stays recoverable when every model-proposed call has a ticket, a contract result, and a line on disk. Wire a free remote lane only after the dry-run log is dull. The dull log is the win.

Cap the Turns: A Weekend Call Envelope for Agent Side Projects

Charlie Hu — Mon, 21 Sep 2026 13:51:58 +0000

A weekend agent loop usually dies from unbounded turns, not from a weak prompt. A file-backed call envelope that refuses the next model or tool invocation after a local budget keeps the experiment from burning idle capacity overnight. The sketch below is small enough to finish in a sitting and strict enough to prove the stop with a test.

The failure this weekend actually needed to stop

Side-project agents retry, reflect, and call tools in a loop. The loop looks healthy. Logs stay green. Tokens still leave the process. Circuit breakers trip on errors. Tool allowlists block the wrong function. Neither construct stops a polite agent that never decides it is done.

Overnight runs make the gap obvious. A single missed max_steps in a toy orchestrator can spend a courtesy budget that was meant to last the week. The envelope treats remaining turns as a first-class resource, not as a comment in a README. Eval suites still matter, but they do not run while the laptop is closed. A hard local halt does.

Scope cut

The lab kept five jobs and dropped the rest. Scope was cut before any client code was written, because the weekend only pays for a working refusal.

In scope

Persist remaining call budget in a JSON file.
Wrap both model calls and tool calls behind one try_consume() gate.
Return a structured refusal the orchestrator can handle without a stack-trace dump.
Ship a CLI to inspect, reset, and dry-run the envelope.
Prove the halt with a unit test that does not talk to a network.

Out of scope for this weekend

Distributed locks across several workers.
Vendor-accurate token billing.
Streaming usage callbacks from a provider.
Multi-tenant quotas.
A web dashboard.

The cut is the point. A finished envelope that stops is more useful than a half-built billing platform.

Envelope rules

The gate is deliberately boring. One process. One file. One lock. Model calls and tool calls share a single counter because weekend agents waste capacity on both.

Event	Remaining calls	Action
`try_consume("model")` and remaining > 0	decrement by 1	allow
`try_consume("tool")` and remaining > 0	decrement by 1	allow
remaining == 0	unchanged	refuse with `EnvelopeEmpty`
`reset(n)`	set to n	allow future consumes
crash mid-write	previous JSON	next start reloads last complete file

Splitting budgets by kind looks sophisticated. It also delays the halt test. That split was left for another sitting.

Working demo

The following Python module is a lab sketch. It is not a production quota service. Copy it into envelope.py and run it locally.

from __future__ import annotations

import argparse
import json
import os
import tempfile
import threading
from dataclasses import dataclass
from pathlib import Path
from typing import Literal

Kind = Literal["model", "tool"]


class EnvelopeEmpty(RuntimeError):
    def __init__(self, kind: Kind, remaining: int) -> None:
        super().__init__(
            f"envelope empty; refused {kind} call; remaining={remaining}"
        )
        self.kind = kind
        self.remaining = remaining


@dataclass
class EnvelopeState:
    remaining: int
    consumed_model: int
    consumed_tool: int

    def to_dict(self) -> dict:
        return {
            "remaining": self.remaining,
            "consumed_model": self.consumed_model,
            "consumed_tool": self.consumed_tool,
        }

    @classmethod
    def from_dict(cls, data: dict) -> "EnvelopeState":
        return cls(
            remaining=int(data["remaining"]),
            consumed_model=int(data.get("consumed_model", 0)),
            consumed_tool=int(data.get("consumed_tool", 0)),
        )


class CallEnvelope:
    def __init__(self, path: Path) -> None:
        self.path = path
        self._lock = threading.Lock()
        self.path.parent.mkdir(parents=True, exist_ok=True)
        if not self.path.exists():
            self._write(
                EnvelopeState(remaining=0, consumed_model=0, consumed_tool=0)
            )

    def _read(self) -> EnvelopeState:
        raw = json.loads(self.path.read_text(encoding="utf-8"))
        return EnvelopeState.from_dict(raw)

    def _write(self, state: EnvelopeState) -> None:
        fd, tmp_name = tempfile.mkstemp(dir=str(self.path.parent), suffix=".tmp")
        try:
            with os.fdopen(fd, "w", encoding="utf-8") as handle:
                json.dump(state.to_dict(), handle, indent=2)
                handle.write("\n")
            os.replace(tmp_name, self.path)
        except Exception:
            if os.path.exists(tmp_name):
                os.remove(tmp_name)
            raise

    def reset(self, remaining: int) -> EnvelopeState:
        if remaining < 0:
            raise ValueError("remaining must be >= 0")
        with self._lock:
            state = EnvelopeState(
                remaining=remaining, consumed_model=0, consumed_tool=0
            )
            self._write(state)
            return state

    def snapshot(self) -> EnvelopeState:
        with self._lock:
            return self._read()

    def try_consume(self, kind: Kind) -> EnvelopeState:
        with self._lock:
            state = self._read()
            if state.remaining <= 0:
                raise EnvelopeEmpty(kind, state.remaining)
            state.remaining -= 1
            if kind == "model":
                state.consumed_model += 1
            else:
                state.consumed_tool += 1
            self._write(state)
            return state


def guarded_model_call(envelope: CallEnvelope, prompt: str) -> str:
    envelope.try_consume("model")
    # Lab stub: replace with the project's real client after tests pass.
    return f"stub-response:{len(prompt)}"


def guarded_tool_call(envelope: CallEnvelope, name: str, payload: dict) -> dict:
    envelope.try_consume("tool")
    return {"tool": name, "ok": True, "echo": payload}


def run_agent_loop(
    envelope: CallEnvelope, steps: list[tuple[Kind, str]]
) -> list[str]:
    log: list[str] = []
    for kind, payload in steps:
        try:
            if kind == "model":
                text = guarded_model_call(envelope, payload)
                log.append(f"model ok: {text}")
            else:
                result = guarded_tool_call(envelope, payload, {"src": "lab"})
                log.append(f"tool ok: {result['tool']}")
        except EnvelopeEmpty as exc:
            log.append(f"halt: {exc}")
            break
    return log


def build_parser() -> argparse.ArgumentParser:
    parser = argparse.ArgumentParser(description="Weekend call envelope")
    parser.add_argument("--path", default=".agent-envelope.json")
    sub = parser.add_subparsers(dest="cmd", required=True)
    reset = sub.add_parser("reset")
    reset.add_argument("remaining", type=int)
    sub.add_parser("status")
    consume = sub.add_parser("consume")
    consume.add_argument("kind", choices=["model", "tool"])
    demo = sub.add_parser("demo")
    demo.add_argument("--budget", type=int, default=3)
    return parser


def main() -> None:
    args = build_parser().parse_args()
    envelope = CallEnvelope(Path(args.path))
    if args.cmd == "reset":
        state = envelope.reset(args.remaining)
        print(json.dumps(state.to_dict()))
        return
    if args.cmd == "status":
        print(json.dumps(envelope.snapshot().to_dict(), indent=2))
        return
    if args.cmd == "consume":
        try:
            state = envelope.try_consume(args.kind)
            print(json.dumps(state.to_dict()))
        except EnvelopeEmpty as exc:
            print(json.dumps({"error": str(exc), "remaining": exc.remaining}))
            raise SystemExit(2)
        return
    if args.cmd == "demo":
        envelope.reset(args.budget)
        steps: list[tuple[Kind, str]] = [
            ("model", "plan the edit"),
            ("tool", "read_file"),
            ("model", "apply the edit"),
            ("tool", "run_tests"),
            ("model", "summarize"),
        ]
        for line in run_agent_loop(envelope, steps):
            print(line)
        print(json.dumps(envelope.snapshot().to_dict(), indent=2))


if __name__ == "__main__":
    main()

The stub model function is intentional. The envelope must be testable without a vendor key. Swap guarded_model_call for the project's real client only after the halt behavior is proven.

Commands to run the demo

python envelope.py reset 3
python envelope.py status
python envelope.py consume model
python envelope.py consume tool
python envelope.py demo --budget 3

Expected demo shape: three successful consumes, then a halt line, then a snapshot with remaining at 0. The fourth and fifth planned steps never run. That refusal is the whole product of the weekend.

Inspect the file after the demo. The JSON is the audit trail this sitting can afford.

cat .agent-envelope.json

A typical snapshot looks like this:

{
  "remaining": 0,
  "consumed_model": 2,
  "consumed_tool": 1
}

If remaining is still positive after five planned steps, the gate never wrapped the loop. Fix that before adding retries, reflection, or a second tool.

Test plan

Save this beside the module as test_envelope.py. The tests never open a socket. If they fail, the envelope is wrong. If they pass, the agent loop can be wired next.

from pathlib import Path

import pytest

from envelope import CallEnvelope, EnvelopeEmpty, run_agent_loop


def test_halt_before_extra_model_call(tmp_path: Path) -> None:
    path = tmp_path / "env.json"
    envelope = CallEnvelope(path)
    envelope.reset(2)
    log = run_agent_loop(
        envelope,
        [
            ("model", "one"),
            ("tool", "two"),
            ("model", "three"),
        ],
    )
    assert log[0].startswith("model ok")
    assert log[1].startswith("tool ok")
    assert log[2].startswith("halt")
    snap = envelope.snapshot()
    assert snap.remaining == 0
    assert snap.consumed_model == 1
    assert snap.consumed_tool == 1


def test_empty_reset_refuses_immediately(tmp_path: Path) -> None:
    envelope = CallEnvelope(tmp_path / "env.json")
    envelope.reset(0)
    with pytest.raises(EnvelopeEmpty):
        envelope.try_consume("model")

pytest test_envelope.py -q

Add one more check when the real client lands: a dry-run flag that records intended consumes without calling the network. The envelope already returns state. Logging that state is cheaper than debugging a surprise bill later.

Parking the loop off the laptop

A local envelope still needs somewhere to run the process. Laptops sleep. SSH sessions drop. A long-lived worker that only has to stay awake is enough for a weekend lab.

MonkeyCode is one lane for that kind of sitting. Disclosure: This article was prepared as part of MonkeyCode's product outreach. The project is open source and, per the operator, offers free model access plus a free server option. The envelope does not depend on that lane. The same JSON file works in front of any client the side project already uses.

Keep the integration boring. Export the envelope path as an environment variable. Run the same python envelope.py demo as a process that outlives a closed lid. Point the real model client at whatever endpoint the lab already trusts. Do not teach the envelope to parse vendor invoices. Call counts are the only signal this weekend believes.

Readers who already keep agent loops on a laptop can park that same process on the free server option if they want the envelope to survive sleep. No other product step is required for the demo to be useful.

What this weekend skipped

Several tempting features were cut on purpose. Each skip kept the demo honest.

Token estimators. Character-length heuristics lie. They create false confidence.
Per-kind budgets. Two counters look neat and delay the halt test.
Redis. A side project with one worker does not need a network lock.
Auto-reset at midnight. Silent refills hide leaks.
Prompt-cache awareness. The envelope counts turns, not billed tokens.
A pretty status page. python envelope.py status already prints JSON.

A green pytest run at the end of the sitting beat a larger design that still called the model "just once more." The skipped list is also a backlog filter: nothing on it is required to stop an unbounded loop.

Limitations and who should skip this

The file is not a ledger. Two processes on one file will race even with os.replace. The lock is in-process only. Crash recovery keeps the last complete JSON, which can lose an in-flight decrement or fail to decrement if the process dies before _write. Neither case is acceptable for paid production traffic.

Do not use this envelope when any of the following is true:

Several workers share one budget.
The agent spends real money and needs vendor-accurate usage.
Compliance requires an immutable audit log.
The orchestrator already has a job queue with a dead-letter path and a max-attempts field that is actually enforced.

Teams with those needs want a real quota service, not a weekend JSON file. The sketch is for a single operator, a single process, and a budget measured in turns rather than currency.

What the sitting actually produced

The working demo is a counter, a refusal, and a test. That is enough to stop a chatty agent before Monday. Wire the project's real model client only after pytest is green. Leave billing, dashboards, and multi-worker locks for a weekend that has already earned them.

Trip the Loop: A Weekend Circuit Breaker for Agent Side Projects

Charlie Hu — Sun, 20 Sep 2026 11:48:01 +0000

Weekend agent side projects rarely die from a missing API key. They die from a loop that keeps calling the same tool, eating turns, and leaving a terminal full of identical errors at 1 a.m. A small in-process circuit breaker — turn cap, identical-call tripwire, consecutive-error open state — is enough to stop that spiral without a platform rewrite.

The pattern below is a scoped weekend demo. It is not a distributed reliability product. It is a fence around a local agent loop so a side project can fail closed instead of fail forever.

The failure that actually shows up

A typical weekend agent looks innocent. One planner. A handful of tools. A while loop until the model says it is done. That loop has no natural end when the model repeats a broken tool call, when JSON parsing fails, or when a search tool returns empty and the planner retries the same query.

Unit tests on the tools do not catch this. The tools are fine. The composition is not. Green tool tests and a runaway planner can coexist for hours, because the suite never asserted that the loop had to stop.

Three trip conditions cover most of that weekend damage:

Turn budget. Hard stop after N planner steps.
Identical call. Open the circuit when the same tool name and payload digest appear K times in a row.
Error streak. Open the circuit after M consecutive tool exceptions.

A wall-clock deadline is a fourth optional fence. It is cheap. It is also easy to get wrong on a laptop that sleeps, so the demo keeps cooldown as a reject counter the tests can drive without time.sleep.

Scope cut for one weekend

The build log is the product. Scope was cut on purpose.

Shipped

In-process state machine: closed, open, half_open
Turn, identical-call, and error-streak trips
A half-open probe that allows one trial call after cooldown
A scripted agent driver and a unit test file that treats "opened" as success

Skipped

Redis or any shared store
Multi-process leases (liveness belongs to a heartbeat, not this fence)
Token spend accounting
Prompt or model lockfiles
A web dashboard
Live model HTTP calls inside the test suite

The skip list is the point. A weekend fence that needs a cluster is not a weekend fence.

Decision table

The breaker answers one question before every tool call: may this loop continue?

State	Event	Next state	Action
closed	turn below max, call is new, tool succeeds	closed	execute
closed	identical payload repeated `k` times	open	reject
closed	consecutive errors reach `m`	open	reject
closed	turn reaches `max_turns`	open	reject
open	cooldown not elapsed	open	reject
open	cooldown elapsed	half_open	reject this call, arm one probe
half_open	probe succeeds	closed	execute and reset counters
half_open	probe fails	open	reject and restart cooldown

Cooldown in the demo is measured in rejected attempts, not wall time. That choice keeps tests deterministic. Wall time can replace the counter later. It should not be the first thing built.

Working demo

The module is a single file. Copy it into tripwire.py. Python 3.10+ is enough. No third-party packages.

# tripwire.py
# Weekend demo: in-process circuit breaker for a local agent loop.
# Proposed pattern, not a production reliability library.

from __future__ import annotations

from dataclasses import dataclass, field
from hashlib import sha256
from typing import Any, Callable, Literal

State = Literal["closed", "open", "half_open"]


def payload_digest(tool: str, payload: Any) -> str:
    raw = f"{tool}:{payload!r}".encode("utf-8")
    return sha256(raw).hexdigest()[:16]


@dataclass
class TripConfig:
    max_turns: int = 8
    identical_limit: int = 3
    error_limit: int = 3
    open_cooldown_rejects: int = 4


@dataclass
class Tripwire:
    config: TripConfig = field(default_factory=TripConfig)
    state: State = "closed"
    turns: int = 0
    identical_streak: int = 0
    error_streak: int = 0
    last_digest: str | None = None
    rejects_while_open: int = 0
    probe_armed: bool = False
    last_reason: str = "ok"

    def precheck(self, tool: str, payload: Any) -> None:
        digest = payload_digest(tool, payload)

        if self.state == "open":
            self.rejects_while_open += 1
            if self.rejects_while_open >= self.config.open_cooldown_rejects:
                self.state = "half_open"
                self.probe_armed = True
                self.rejects_while_open = 0
            self.last_reason = "circuit_open"
            raise RuntimeError("circuit_open")

        if self.state == "half_open":
            if not self.probe_armed:
                self.last_reason = "circuit_open"
                raise RuntimeError("circuit_open")
            self.probe_armed = False

        if self.turns >= self.config.max_turns:
            self._open("max_turns")

        if self.last_digest == digest:
            self.identical_streak += 1
        else:
            self.identical_streak = 1
            self.last_digest = digest

        if self.identical_streak >= self.config.identical_limit:
            self._open("identical_call")

    def record_success(self) -> None:
        self.turns += 1
        self.error_streak = 0
        if self.state == "half_open":
            self.state = "closed"
            self.identical_streak = 0
            self.probe_armed = False
        self.last_reason = "ok"

    def record_error(self, exc: BaseException) -> None:
        self.turns += 1
        self.error_streak += 1
        if self.state == "half_open" or self.error_streak >= self.config.error_limit:
            self._open("error_streak")
        self.last_reason = type(exc).__name__

    def _open(self, reason: str) -> None:
        self.state = "open"
        self.rejects_while_open = 0
        self.probe_armed = False
        self.last_reason = reason
        raise RuntimeError(reason)


def run_agent(
    steps: list[tuple[str, Any, bool]],
    breaker: Tripwire,
    tool_fn: Callable[[str, Any], str],
) -> list[str]:
    """Drive a scripted agent. Each step is (tool, payload, should_succeed)."""
    outputs: list[str] = []
    for tool, payload, should_succeed in steps:
        breaker.precheck(tool, payload)
        try:
            if not should_succeed:
                raise ValueError("tool_failed")
            result = tool_fn(tool, payload)
            breaker.record_success()
            outputs.append(result)
        except RuntimeError:
            raise
        except Exception as exc:
            breaker.record_error(exc)
            raise
    return outputs

A tiny driver shows the fence without a model:

# demo_loop.py
from tripwire import TripConfig, Tripwire, run_agent


def echo(tool: str, payload: object) -> str:
    return f"{tool}:{payload}"


def main() -> None:
    breaker = Tripwire(TripConfig(max_turns=5, identical_limit=3, error_limit=3))
    script = [
        ("search", "circuit breaker agent loop", True),
        ("search", "circuit breaker agent loop", True),
        ("search", "circuit breaker agent loop", True),  # should trip
    ]
    try:
        print(run_agent(script, breaker, echo))
    except RuntimeError as err:
        print(f"tripped state={breaker.state} reason={err}")


if __name__ == "__main__":
    main()

Run it:

python demo_loop.py

Expected line:

tripped state=open reason=identical_call

The third identical search never becomes a fourth attempt. That is the whole weekend win. The planner can still be wrong. It just cannot be wrong forever in the same way.

Tests that fail closed

Naive agent tests assert that a tool returned JSON. They do not assert that the loop stopped. The suite below treats "the breaker opened" as the successful outcome.

# test_tripwire.py
import unittest

from tripwire import TripConfig, Tripwire, run_agent


def echo(tool: str, payload: object) -> str:
    return f"{tool}:{payload}"


class TripwireTests(unittest.TestCase):
    def test_identical_call_opens(self) -> None:
        b = Tripwire(TripConfig(identical_limit=3, max_turns=20))
        steps = [("search", "same", True)] * 3
        with self.assertRaisesRegex(RuntimeError, "identical_call"):
            run_agent(steps, b, echo)
        self.assertEqual(b.state, "open")

    def test_error_streak_opens(self) -> None:
        b = Tripwire(TripConfig(error_limit=3, max_turns=20, identical_limit=9))
        steps = [("fetch", i, False) for i in range(3)]
        with self.assertRaisesRegex(RuntimeError, "error_streak"):
            run_agent(steps, b, echo)
        self.assertEqual(b.state, "open")

    def test_max_turns_opens(self) -> None:
        b = Tripwire(TripConfig(max_turns=2, identical_limit=9, error_limit=9))
        steps = [("think", "a", True), ("think", "b", True), ("think", "c", True)]
        with self.assertRaisesRegex(RuntimeError, "max_turns"):
            run_agent(steps, b, echo)

    def test_half_open_probe_closes(self) -> None:
        b = Tripwire(
            TripConfig(
                max_turns=50,
                identical_limit=9,
                error_limit=2,
                open_cooldown_rejects=2,
            )
        )
        with self.assertRaisesRegex(RuntimeError, "error_streak"):
            run_agent([("fetch", 1, False), ("fetch", 2, False)], b, echo)

        for _ in range(2):
            with self.assertRaisesRegex(RuntimeError, "circuit_open"):
                b.precheck("fetch", "probe-wait")

        b.precheck("fetch", "unique-ok")
        b.record_success()
        self.assertEqual(b.state, "closed")


if __name__ == "__main__":
    unittest.main()

python -m unittest test_tripwire.py -v

Four tests. No network. No fixtures that rot when a vendor changes a chat template. The assertions pin control-plane behavior, which is the part a weekend agent actually loses.

Identical-call hashing uses repr of the payload. That is good enough for strings, ints, and small tuples in a demo. It is a poor canonical form for unordered dicts, objects with changing ids, or floating timestamps injected by the planner. If those show up, normalize the payload before payload_digest, or the tripwire will never see a repeat.

Where a hosted planner fits

Local scripted steps are enough to prove the fence. A real planner still needs a model at some point. That is a different layer from the tripwire. Mixing them in the first weekend usually produces an integration test that fails for reasons that have nothing to do with the breaker.

Disclosure: This article was prepared as part of MonkeyCode's product outreach.

When the scripted loop is green and the next step is to point a planner at a live model, MonkeyCode's free model access and free server option are one way to host that planner without standing up a GPU box first. Keep the tripwire on the caller side, next to the tool calls, so an open circuit does not depend on a remote dashboard.

That split is the useful part. The fence is local, deterministic, and tested. The model is optional and replaceable.

What this will not do

The demo does not coordinate two processes. Two agent workers can still double-call a tool. It does not inspect tool side effects, so a breaker that opens after a successful destructive write is already too late. It does not prove the model is truthful. It only proves the loop stopped.

People who should not use this as-is:

Anyone running multi-tenant or billed agents. In-process state is not an isolation boundary.
Anyone who needs a hard real-time deadline. The cooldown is a reject counter, not a clock.
Anyone who already has a workflow engine with retries and sagas. Do not stack a second policy object on top without mapping states.
Anyone treating "circuit closed" as a safety sign-off for generated code or destructive tools.

A merge gate for generated diffs is a different weekend. A tool allowlist is a different weekend. This fence only bounds the loop.

Build log: what moved and what did not

The first cut tried to hash the entire conversation and trip on a repeated trace. That was too coarse. A planner can legally retry with a small payload change. Hashing the tool name plus payload, and only counting consecutive repeats, matched the failure that actually happened: the same search, three times, no new information.

The second cut wanted wall-clock timeouts. Tests then needed sleep and became flaky on a laptop that throttled. The reject-counter cooldown replaced it. Wall time can come back when the breaker is wired to a real scheduler.

The third cut wanted to log every trip to a JSONL file. Useful later. Not required to prove the state machine. The last_reason field is enough for a weekend demo and for the tests.

Half-open took longer than the closed/open pair. Allowing the cooldown-completing call to run as a probe mixed "I am still rejecting" with "I am testing recovery" in the same request. The demo now rejects the call that arms the probe, then allows exactly one later call. That is easier to test. It also matches how most human operators think about a cooling-off period: the last failure does not get a free retry.

What shipped is a tripwire a side project can paste, run, and keep. What did not ship is a platform. That is the correct ending for a Sunday night.

Seal the Tools: A Weekend Allowlist for Agent Side Projects

Charlie Hu — Sat, 19 Sep 2026 09:52:19 +0000

A weekend agent loop is not engineering until tool calls are sealed. The demo below is a local allowlist plus a fail-closed circuit breaker. It is small enough to finish in a sitting, and it still stops a runaway agent from inventing rm, curl, or a second write path.

Side-project agents fail in a boring way. The model proposes a tool name. The host executes it. The filesystem or the network takes the hit. Spend meters and step ledgers cap volume. They do not decide which verbs are legal.

This build log cuts scope to three verbs, ships a working CLI, and lists what was skipped. The code is a proposal that runs locally. It is not a production agent runtime.

Why tool calls leak first

Vibe-driven loops look productive because text appears. Side effects are the real work. A model that can call write_file, run_shell, and http_fetch can also rename those tools, widen a path, or retry a failing call until a quota or a disk fills.

Volume controls do not answer the verb question. A step ledger can say “stop after 40 turns.” An allowlist says “this turn may only write_file under ./out, with these keys, and this size.” The second check is the one that keeps a weekend repo intact.

The failure mode is not clever jailbreaks. It is an unconstrained dispatcher. One Python process that treats the model’s JSON as a command line will eventually execute a name nobody reviewed.

Scope cut for one weekend

The box is a single process, one JSON allowlist, and a breaker that opens after repeated rejects. No model client lives in the repo. A fixture file stands in for model output so the gate can be tested without network calls.

In scope

Three tools: write_file, read_file, list_dir
Path prefix checks under ./workspace
Argument key and type checks
Byte cap on writes
A fail-closed breaker after N consecutive denials
A CLI that prints ALLOW or DENY and a reason code

Out of scope

Shell, HTTP, or package install tools
Multi-user auth
Streaming model APIs
Distributed locks
Prompt storage

The cut is deliberate. A weekend that also wraps curl and docker will ship neither a gate nor a demo. Three file tools still cover the usual side-project damage: clobbering source, reading secrets outside the tree, and writing megabyte junk.

Decision table

Incoming call	Allowlist result	Breaker state	Host action
`write_file` under `./workspace/out`, 4 KiB	allow	closed	execute
`write_file` under `../.ssh`	deny `PATH_ESCAPE`	closed	skip
`run_shell`	deny `UNKNOWN_TOOL`	closed	skip
same unknown tool, 5th time	deny `UNKNOWN_TOOL`	open	halt loop
any tool after halt	deny `BREAKER_OPEN`	open	exit non-zero

The table is the product. Code below is only a way to make those rows executable.

Artifact: allowlist file

Keep the policy in JSON so a diff review can see it. YAML is nicer to type and worse to pin in tests. The weekend file lives at tools.allow.json.

{
  "workspace_root": "./workspace",
  "max_write_bytes": 65536,
  "breaker_threshold": 5,
  "tools": {
    "write_file": {
      "keys": ["path", "content"],
      "path_key": "path",
      "must_stay_under": "out",
      "content_key": "content"
    },
    "read_file": {
      "keys": ["path"],
      "path_key": "path",
      "must_stay_under": ""
    },
    "list_dir": {
      "keys": ["path"],
      "path_key": "path",
      "must_stay_under": ""
    }
  }
}

Empty must_stay_under still means “inside workspace_root.” Nested out is extra fence for writes. Reads may look at notes and fixtures. Writes may not.

Artifact: the gate

The gate is one module. It resolves paths with Path.resolve(), compares prefixes, and never calls eval. Consecutive denials increment a counter stored in breaker.json. A success resets it. An open breaker refuses every later call, including legal ones, until a human deletes the file.

# gate.py — weekend allowlist + fail-closed breaker
from __future__ import annotations

import json
from dataclasses import dataclass
from pathlib import Path

@dataclass(frozen=True)
class Decision:
    allow: bool
    code: str
    detail: str

class ToolGate:
    def __init__(self, policy_path: Path, breaker_path: Path) -> None:
        self.policy = json.loads(policy_path.read_text(encoding="utf-8"))
        self.breaker_path = breaker_path
        self.root = Path(self.policy["workspace_root"]).resolve()
        self.root.mkdir(parents=True, exist_ok=True)

    def _breaker(self) -> dict:
        if not self.breaker_path.exists():
            return {"denies": 0, "open": False}
        return json.loads(self.breaker_path.read_text(encoding="utf-8"))

    def _save_breaker(self, state: dict) -> None:
        self.breaker_path.write_text(json.dumps(state), encoding="utf-8")

    def _trip(self, allowed: bool) -> None:
        state = self._breaker()
        if allowed:
            state = {"denies": 0, "open": False}
        else:
            state["denies"] = int(state.get("denies", 0)) + 1
            if state["denies"] >= int(self.policy["breaker_threshold"]):
                state["open"] = True
        self._save_breaker(state)

    def _inside(self, target: Path, extra: str) -> bool:
        base = (self.root / extra).resolve() if extra else self.root
        try:
            target.relative_to(base)
            return True
        except ValueError:
            return False

    def check(self, name: str, args: dict) -> Decision:
        state = self._breaker()
        if state.get("open"):
            return Decision(False, "BREAKER_OPEN", "human reset required")

        spec = self.policy["tools"].get(name)
        if spec is None:
            self._trip(False)
            return Decision(False, "UNKNOWN_TOOL", name)

        expected = list(spec["keys"])
        if set(args) != set(expected):
            self._trip(False)
            return Decision(False, "BAD_KEYS", f"want {expected} got {sorted(args)}")

        rel = args[spec["path_key"]]
        if not isinstance(rel, str) or rel.startswith("/") or "\\" in rel:
            self._trip(False)
            return Decision(False, "BAD_PATH", "relative posix path required")

        target = (self.root / rel).resolve()
        if not self._inside(target, spec.get("must_stay_under", "")):
            self._trip(False)
            return Decision(False, "PATH_ESCAPE", str(target))

        content_key = spec.get("content_key")
        if content_key:
            body = args.get(content_key, "")
            if not isinstance(body, str):
                self._trip(False)
                return Decision(False, "BAD_CONTENT", "content must be str")
            if len(body.encode("utf-8")) > int(self.policy["max_write_bytes"]):
                self._trip(False)
                return Decision(False, "TOO_LARGE", "write exceeds cap")

        self._trip(True)
        return Decision(True, "OK", name)

A thin CLI keeps the gate usable from a shell or from a later agent host.

# check_call.py
import json, sys
from pathlib import Path
from gate import ToolGate

def main() -> int:
    payload = json.loads(Path(sys.argv[1]).read_text(encoding="utf-8"))
    gate = ToolGate(Path("tools.allow.json"), Path("breaker.json"))
    decision = gate.check(payload["tool"], payload.get("args") or {})
    print(json.dumps({"allow": decision.allow, "code": decision.code, "detail": decision.detail}))
    return 0 if decision.allow else 2

if __name__ == "__main__":
    raise SystemExit(main())

Working demo

Create the policy file, then two fixtures. The first is a legal write. The second is a tool the policy never named.

mkdir -p workspace/out fixtures
cat > fixtures/ok_write.json << 'EOF'
{"tool": "write_file", "args": {"path": "out/note.md", "content": "# weekend note\n"}}
EOF
cat > fixtures/bad_shell.json << 'EOF'
{"tool": "run_shell", "args": {"cmd": "echo no"}}
EOF
python check_call.py fixtures/ok_write.json
python check_call.py fixtures/bad_shell.json

Expected stdout, in order:

{"allow": true, "code": "OK", "detail": "write_file"}
{"allow": false, "code": "UNKNOWN_TOOL", "detail": "run_shell"}

Repeat the bad fixture until the threshold trips. The fifth denial should return BREAKER_OPEN on every later call, including the legal write. Reset is a file delete, not a model retry.

for i in 1 2 3 4 5; do python check_call.py fixtures/bad_shell.json; done
python check_call.py fixtures/ok_write.json
rm -f breaker.json
python check_call.py fixtures/ok_write.json

That last pair is the demo worth keeping. The loop cannot talk itself out of an open breaker. A human has to touch disk.

Tiny test plan

The tests are the build’s memory. They pin path escape, extra keys, and breaker latch without a model.

# test_gate.py
import json
from pathlib import Path
from gate import ToolGate

def policy(tmp: Path) -> Path:
    p = tmp / "tools.allow.json"
    p.write_text(json.dumps({
        "workspace_root": str(tmp / "workspace"),
        "max_write_bytes": 64,
        "breaker_threshold": 3,
        "tools": {
            "write_file": {
                "keys": ["path", "content"],
                "path_key": "path",
                "must_stay_under": "out",
                "content_key": "content",
            }
        },
    }), encoding="utf-8")
    return p

def test_blocks_parent_escape(tmp_path):
    g = ToolGate(policy(tmp_path), tmp_path / "breaker.json")
    d = g.check("write_file", {"path": "../secret.txt", "content": "x"})
    assert d.allow is False and d.code == "PATH_ESCAPE"

def test_opens_breaker(tmp_path):
    g = ToolGate(policy(tmp_path), tmp_path / "breaker.json")
    for _ in range(3):
        g.check("run_shell", {"cmd": "x"})
    d = g.check("write_file", {"path": "out/a.txt", "content": "ok"})
    assert d.code == "BREAKER_OPEN"

Run with pytest -q test_gate.py. If pytest is missing, the CLI loop above is enough for a weekend check. The tests exist so the next sitting does not “simplify” prefix logic and re-open ../.

Where a free hosted loop fits

The gate is local on purpose. A laptop still has the author’s ssh keys, browser profiles, and other repos. Running the same loop on a throwaway machine reduces how much a missed path check can touch.

Disclosure: This article was prepared as part of MonkeyCode's product outreach. MonkeyCode’s free model access and free server option are a place to exercise the allowlist against a hosted loop without standing up a private GPU box. The gate does not depend on that host. The CLI still runs on a laptop with Python 3.11+ and the JSON files above.

Keep the policy file in the repo that the server mounts. Do not bake tool names into prompts only. Prompts drift. The JSON file is the review surface.

What this weekend skipped

The skip list is part of the log. Each item is a future sitting, not a hidden feature.

No shell tool. Command strings are a second language. An allowlist of argv templates is a different article.
No content scanners. The byte cap stops accidental dumps. It does not detect secrets already in content.
No idempotency keys. A retried write_file can clobber a good file after a legal allow.
No audit chain. breaker.json is a counter, not a signed log.
No model adapter. Wiring a vendor SDK would make the demo look complete and make the tests flaky.

Skipping those kept the artifact honest. A host that prints ALLOW and then shells out to an unlisted binary has no allowlist. The execution path has to call check before any write_text.

A minimal host sketch, labeled as unexecuted glue:

# host_sketch.py — proposal, not a full agent
# decision = gate.check(name, args)
# if not decision.allow:
#     return decision
# Path(root, args["path"]).write_text(args["content"], encoding="utf-8")

Wire that after the tests pass. Not before.

Limitations and who should not use this

The prefix check uses resolve() and relative_to(). Symlinks that jump out of workspace before resolve can still surprise a host that creates links. Weekend side projects that mount extra volumes should refuse symlinks or check Path.stat().st_ino against the root device. This demo does neither.

The breaker is a local JSON file. Two processes racing on it can under-count denials. That is acceptable for a single weekend worker. It is not acceptable for a shared CI lane.

Argument checks are exact key sets. Extra harmless keys are denied. Missing keys are denied. That is strict and slightly annoying. Strict is the point. Models pad JSON. Padding should fail closed.

Do not use this approach when any of the following hold:

The agent must run arbitrary shell as a product requirement
The workspace contains production credentials
Several workers share one breaker file
Compliance needs an append-only audit log
The operator cannot review tools.allow.json before each sitting

Those cases need a real sandbox, a job queue, and a person on call. A 150-line gate is a seatbelt for a side project. It is not a vehicle inspection.

The useful result is social as much as technical. A pull request that adds run_shell has to change tools.allow.json. Reviewers see the verb. That is the whole point of sealing tools on a weekend: make the dangerous change visible, then keep the breaker in front of every call.

Readers who already have a loop can drop gate.py in front of their dispatcher. Those who want the same checks against a hosted worker can run the loop with MonkeyCode’s free model access and free server option, still behind this allowlist.

Lease the Worker: A Weekend Heartbeat for Agent Side Projects

Charlie Hu — Fri, 18 Sep 2026 08:12:11 +0000

An agent side project on a spare machine is not finished when the prompt looks clever. It is finished when the worker process holds a lease, writes a heartbeat, and dies on a hard stop. Wall-clock time is a first-class resource, the same way a step counter is a first-class resource for loops.

This weekend recipe is a supervisor plus a worker. The supervisor owns the clock. The worker only proves it is alive. The demo stays small enough to run with the Python standard library and a single terminal.

The failure this cuts

Weekend agents fail in a boring way. They retry a model call. They block on a tool. They wait for a human who already closed the laptop. A token spend meter does not catch a stuck HTTP client. A step ledger does not catch one tool call that never returns.

A process lease covers that gap. The happy path can still be drafted by a model. The lease still ends. That split is the whole point of the weekend: keep generation cheap, keep runtime finite.

Recent discussion around “vibe coding” versus engineering is noisy. This recipe ignores the slogan fight. It adds one engineering object a demo actually needs: an expiry.

Scope cut for Saturday and Sunday

Three files are in scope.

lease.json — holder, deadline, last pulse, terminal status
supervise.py — spawn, poll, kill the process group
worker.py — do one bounded job and rewrite the lease on a timer

Everything else is skipped on purpose.

No containers, Kubernetes, or systemd units
No multi-tenant isolation or public ingress
No TLS, API keys in source, or secret stores
No vendor SDK beyond a tiny optional HTTP stub
No auto-restart storms, backoff graphs, or Slack alerts

A watchdog a reader can run with python3 supervise.py beats a cluster diagram that never boots. The cut is the product.

The lease document

The lease is a JSON file on local disk. File locks are enough for a single-machine weekend. The supervisor is the only writer of status values running, expired, killed, and done. The worker may update heartbeat_unix and note only while status is running.

# lease_schema.py — shape only, no framework
LEASE_EXAMPLE = {
    "lease_id": "wknd-20260918",
    "holder_pid": 0,
    "budget_sec": 180,
    "started_unix": 0,
    "deadline_unix": 0,
    "heartbeat_unix": 0,
    "heartbeat_max_gap_sec": 8,
    "status": "running",
    "note": "boot",
}

A reader who wants a stricter file can add a generation integer later. This weekend does not. One file, one holder, one clock.

Supervisor: spawn, poll, kill

supervise.py creates the lease, starts the worker in a new session, then polls. Missing heartbeats and crossed deadlines both become a kill. The kill targets the process group so child model clients die with the worker.

#!/usr/bin/env python3
"""Weekend process lease. Proposal: run locally, not as a cluster controller."""
from __future__ import annotations

import json
import os
import signal
import subprocess
import sys
import time
from pathlib import Path

LEASE = Path("lease.json")
WORKER = [sys.executable, "worker.py", str(LEASE)]
BUDGET_SEC = 180
GAP_SEC = 8
POLL_SEC = 1.0


def write_lease(doc: dict) -> None:
    tmp = LEASE.with_suffix(".tmp")
    tmp.write_text(json.dumps(doc, indent=2), encoding="utf-8")
    tmp.replace(LEASE)


def read_lease() -> dict:
    return json.loads(LEASE.read_text(encoding="utf-8"))


def main() -> int:
    now = time.time()
    write_lease(
        {
            "lease_id": "wknd-local",
            "holder_pid": 0,
            "budget_sec": BUDGET_SEC,
            "started_unix": now,
            "deadline_unix": now + BUDGET_SEC,
            "heartbeat_unix": now,
            "heartbeat_max_gap_sec": GAP_SEC,
            "status": "running",
            "note": "supervisor-boot",
        }
    )
    proc = subprocess.Popen(
        WORKER,
        start_new_session=True,
        stdout=sys.stdout,
        stderr=sys.stderr,
    )
    doc = read_lease()
    doc["holder_pid"] = proc.pid
    write_lease(doc)

    exit_code = 0
    while True:
        time.sleep(POLL_SEC)
        doc = read_lease()
        now = time.time()
        alive = proc.poll() is None

        if not alive:
            if doc.get("status") != "done":
                doc["status"] = "killed"
                doc["note"] = f"worker-exit-{proc.returncode}"
                write_lease(doc)
                exit_code = proc.returncode or 1
            break

        if now > float(doc["deadline_unix"]):
            doc["status"] = "expired"
            doc["note"] = "budget-exceeded"
            write_lease(doc)
            os.killpg(proc.pid, signal.SIGKILL)
            proc.wait()
            exit_code = 2
            break

        gap = now - float(doc["heartbeat_unix"])
        if gap > float(doc["heartbeat_max_gap_sec"]):
            doc["status"] = "killed"
            doc["note"] = f"heartbeat-gap-{gap:.1f}s"
            write_lease(doc)
            os.killpg(proc.pid, signal.SIGKILL)
            proc.wait()
            exit_code = 3
            break

        if doc.get("status") == "done":
            proc.wait()
            break

    print(json.dumps(read_lease(), indent=2))
    return exit_code


if __name__ == "__main__":
    raise SystemExit(main())

The supervisor never parses model output. That is deliberate. Parsing belongs in the worker, behind the lease.

Worker: pulse, then one bounded job

The worker rewrites heartbeat_unix on a short interval. A daemon thread handles the pulse so a blocking tool call cannot silently freeze the file. The job itself is a stub: read a task file, optionally ask a model, write out/result.json, mark done.

#!/usr/bin/env python3
"""Weekend worker. Proposal: one task, then exit. Not a long-running agent OS."""
from __future__ import annotations

import json
import os
import sys
import threading
import time
import urllib.error
import urllib.request
from pathlib import Path

STOP = threading.Event()


def pulse(lease_path: Path) -> None:
    while not STOP.is_set():
        doc = json.loads(lease_path.read_text(encoding="utf-8"))
        if doc.get("status") != "running":
            break
        doc["heartbeat_unix"] = time.time()
        doc["note"] = f"pid-{os.getpid()}"
        tmp = lease_path.with_suffix(".tmp")
        tmp.write_text(json.dumps(doc, indent=2), encoding="utf-8")
        tmp.replace(lease_path)
        STOP.wait(2.0)


def maybe_model(prompt: str) -> str:
    """Optional HTTP stub. Leave MODEL_URL unset to skip the network."""
    url = os.environ.get("MODEL_URL", "").strip()
    if not url:
        return json.dumps({"ok": True, "echo": prompt[:240]})
    body = json.dumps({"prompt": prompt}).encode("utf-8")
    req = urllib.request.Request(
        url,
        data=body,
        headers={"Content-Type": "application/json"},
        method="POST",
    )
    try:
        with urllib.request.urlopen(req, timeout=20) as resp:
            return resp.read().decode("utf-8")[:4000]
    except (urllib.error.URLError, TimeoutError) as exc:
        return json.dumps({"ok": False, "error": str(exc)})


def main() -> int:
    lease_path = Path(sys.argv[1])
    t = threading.Thread(target=pulse, args=(lease_path,), daemon=True)
    t.start()

    task = Path("task.txt")
    prompt = task.read_text(encoding="utf-8") if task.exists() else "summarize lease.json"
    Path("out").mkdir(exist_ok=True)
    Path("out/result.json").write_text(maybe_model(prompt), encoding="utf-8")

    doc = json.loads(lease_path.read_text(encoding="utf-8"))
    doc["status"] = "done"
    doc["heartbeat_unix"] = time.time()
    doc["note"] = "worker-complete"
    lease_path.write_text(json.dumps(doc, indent=2), encoding="utf-8")
    STOP.set()
    return 0


if __name__ == "__main__":
    raise SystemExit(main())

The stub keeps the demo honest. A missing MODEL_URL still produces out/result.json. Network is optional. The lease is not.

Where a free model and a free server actually participate

A laptop can run this pair during development. A side project that should keep running after the lid closes needs two other pieces: a model that can draft the next action, and a machine that can host supervise.py.

Disclosure: This article was prepared as part of MonkeyCode's product outreach. MonkeyCode offers free model access and a free server option. Those two facts are the only product claims used here. No model names, quotas, hardware sketches, or benchmark numbers are attached, because those details change and do not belong in a weekend recipe.

The mapping is mechanical.

Free model access sits behind MODEL_URL when a reader wants the worker to draft text instead of echoing the task file.
The free server option is a place to run supervise.py so the lease is enforced away from the laptop.
The lease does not care which model answered. It cares that the process still pulses, then exits.

If those hosted pieces are unavailable, the same scripts still run locally. The article remains useful with the product names removed.

Working demo

From a clean directory:

chmod +x supervise.py worker.py
echo "list three risks of an unbounded agent loop" > task.txt
python3 supervise.py
cat lease.json
cat out/result.json

Expected shape after a healthy run: status is done, holder_pid is nonzero, and out/result.json exists. Expected shape after a hang: status is killed or expired, and the process group is gone.

Reproducible hang test

Label this as an unexecuted example until a reader actually runs it. Replace the job body in worker.py with time.sleep(999) and leave the pulse thread in place. The supervisor should still pass, because heartbeats continue. Then comment out the pulse thread and sleep again. The supervisor should exit with code 3 and note starting with heartbeat-gap-.

A second test sets BUDGET_SEC = 5 and sleeps 30 with pulses enabled. The supervisor should exit with code 2 and status expired.

Test plan
1. Happy path: task.txt present, MODEL_URL unset, expect status=done, exit 0.
2. Pulse failure: disable pulse thread, expect status=killed, exit 3.
3. Budget failure: BUDGET_SEC=5, worker sleeps 30, expect status=expired, exit 2.
4. Child cleanup: worker spawns `sleep 120`; after kill, `pgrep -f sleep` is empty.

Decision table for the weekend

Signal	Supervisor action	Worker duty
Heartbeat fresh, before deadline	Keep polling	Continue job
Heartbeat gap over limit	SIGKILL process group	None; already stuck
Deadline crossed	Mark `expired`, SIGKILL	None
Worker sets `done`	Wait, print lease, exit 0	Stop pulsing
Worker exits nonzero	Mark `killed`	Crash or bug

The table is the demo contract. Anything not in the table is next weekend.

What this weekend skipped

Several tempting features were left on the floor.

Restart policies. Auto-restart turns a bad tool into a fork bomb. A lease that ends is easier to reason about than a lease that reincarnates.
Distributed clocks. NTP skew exists. A single machine clock is enough for 180 seconds.
Patch review. Bounding process lifetime is not bounding diff size. A separate checker would be another article.
Cassette recording of model HTTP. Call tracing is useful. It is also a different object from a heartbeat.
Spend preflight. Cost caps do not stop a hung recv().
Pretty dashboards. cat lease.json is the UI.

Skipping is how a weekend demo stays shippable. Each skipped item is a real problem. None of them is required to prove the lease works.

Limitations, and who should not use this

This watchdog is not a security boundary. A worker that can write lease.json can fake a heartbeat. A worker that can send signals can fight the supervisor. Run it only on a throwaway side-project directory, as the same user, with no secrets in the tree.

JSON on disk will tear if a second supervisor starts. start_new_session=True is Unix-shaped; Windows needs a different kill story. The HTTP stub has no auth. Daemon threads will not save a process that deadlocks inside the interpreter in a way that blocks all Python progress; for that class of hang, an outer timeout from the shell is still required.

Do not use this as:

a production orchestrator for paying customers
a multi-tenant sandbox
a merge gate for generated patches
a substitute for cgroups, seccomp, or containers
a billing system

Teams with existing Nomad, systemd, or Kubernetes Jobs should keep those. The weekend lease is for a solo demo that previously ran until the laptop fan became the alert.

Closing shape

The core object is small. A JSON lease, a pulse thread, a supervisor that kills a process group. Model output is optional. Runtime is not. That is enough engineering to keep a free-tier side project from becoming an unbounded process.

Readers who want a hosted model endpoint or a machine that is not a laptop can plug those into MODEL_URL and the server that runs supervise.py. The first proof is still local: one hang test, one expiry test, one lease.json that says the worker stopped.

Tape the Model Calls: A Weekend Cassette for Agent Side Projects

Charlie Hu — Thu, 17 Sep 2026 06:39:13 +0000

Weekend agent demos rot when every click needs a live model round-trip. Record the request and response once, replay that tape for the demo, and keep any live call behind an explicit latch. The working artifact is a fail-closed cassette, not a new agent framework.

This log cuts scope to a single Python harness, a JSONL tape, and three commands that prove replay. It does not argue that models write better code than people. It treats flaky live traffic as an engineering leak in a side project that has to ship on Sunday night.

Scope for one weekend

The cassette owns three jobs. It canonicalizes a model request. It stores one JSON object per hash. It refuses to hit the network unless the operator flips a latch.

Out of scope on purpose:

streaming tokens and partial deltas
provider-specific SDKs and invented model names
encryption at rest or a shared team vault
prompt evals, leaderboards, or quality scores
write side effects against production data

The demo is a CLI that answers a fixed ticket (summarize the failing test) from tape. If the tape misses, the process exits non-zero. That is the whole show.

The failure mode

Live calls hide three bugs that look like product progress. Latency jitter makes the same prompt feel different on the second run. A changed system message silently invalidates last week's screenshot. A weekend quota or a free server blip turns a recorded talk track into an apology.

A cassette does not make the model wiser. It makes the demo honest. Replay is a reducer: same bytes in, same bytes out, or a hard miss.

The cassette contract

The tape is append-only JSONL. Each line is one recorded exchange. The key is a SHA-256 of a canonical request, not a timestamp and not a filename the operator typed by hand.

# layout
.cassettes/
  agent-demo.jsonl

Canonical form is a UTF-8 JSON object with sorted keys and no insignificant whitespace. Fields that do not change the model’s job are stripped before hashing: wall-clock timestamps, client request ids, and local absolute paths.

# cassette.py — weekend sketch, not a published library
from __future__ import annotations

import hashlib, json, os
from pathlib import Path
from typing import Any, Callable, Literal

Mode = Literal["replay", "record", "live"]

STRIP = {"timestamp", "request_id", "cwd"}


def canonicalize(req: dict[str, Any]) -> str:
    body = {k: v for k, v in req.items() if k not in STRIP}
    return json.dumps(body, sort_keys=True, separators=(",", ":"), ensure_ascii=False)


def req_hash(req: dict[str, Any]) -> str:
    return hashlib.sha256(canonicalize(req).encode("utf-8")).hexdigest()


class Cassette:
    def __init__(self, path: Path, mode: Mode, live: Callable[[dict[str, Any]], dict[str, Any]]):
        self.path = path
        self.mode = mode
        self.live = live
        self.path.parent.mkdir(parents=True, exist_ok=True)
        self._index = self._load()

    def _load(self) -> dict[str, dict[str, Any]]:
        if not self.path.exists():
            return {}
        out: dict[str, dict[str, Any]] = {}
        for line in self.path.read_text(encoding="utf-8").splitlines():
            if not line.strip():
                continue
            row = json.loads(line)
            out[row["hash"]] = row
        return out

    def call(self, req: dict[str, Any]) -> dict[str, Any]:
        key = req_hash(req)
        if self.mode == "replay":
            if key not in self._index:
                raise SystemExit(f"cassette miss: {key[:12]}")
            return self._index[key]["response"]
        if self.mode == "record" and key in self._index:
            return self._index[key]["response"]
        if self.mode != "live" and os.environ.get("DEMO_LIVE") != "1":
            raise SystemExit("live latch is off; set DEMO_LIVE=1 to recapture")
        response = self.live(req)
        row = {"hash": key, "request": json.loads(canonicalize(req)), "response": response}
        with self.path.open("a", encoding="utf-8") as fh:
            fh.write(json.dumps(row, ensure_ascii=False) + "\n")
        self._index[key] = row
        return response

Replay never calls live. Record reuses a hit and only captures a miss when the latch is on. Live always captures. Those three sentences are the contract. Everything else is ceremony.

A stub live function, labeled as a stub

The weekend build does not ship a vendor client. The live function is an injected callable so the cassette stays testable without inventing endpoints, model names, or quotas.

# live_stub.py — example only; replace with a real client in the operator’s repo

def live_echo(req: dict) -> dict:
    prompt = req["prompt"]
    return {
        "text": f"STUB:{prompt[:80]}",
        "usage": {"input_chars": len(prompt), "output_chars": 0},
    }

When a real client exists, it should return a JSON-serializable dict and nothing else. Binary blobs and iterator streams are skipped this weekend. They break the tape format.

Tiny agent loop

The agent is a function, not a platform. It builds one request, asks the cassette, and prints one line. No tool loop. No retries. No hidden second call.

# demo.py
import os
from pathlib import Path
from cassette import Cassette
from live_stub import live_echo

TICKET = "summarize the failing test: test_invoice_total"

def build_request(ticket: str) -> dict:
    return {
        "task": "ticket-summary",
        "prompt": ticket,
        "max_output_chars": 400,
    }

def main() -> None:
    mode = os.environ.get("CASSETTE_MODE", "replay")
    tape = Cassette(Path(".cassettes/agent-demo.jsonl"), mode, live_echo)  # type: ignore[arg-type]
    text = tape.call(build_request(TICKET))["text"]
    print(text)

if __name__ == "__main__":
    main()

Third-person rule for the demo script: the operator exports mode, runs the file, and reads stdout. No dashboard. No spinner. The golden path is replay.

Commands that prove the demo

Capture once, with the latch on. Then freeze the tape and turn the latch off.

mkdir -p .cassettes
export CASSETTE_MODE=record
export DEMO_LIVE=1
python demo.py | tee /tmp/demo-once.txt

unset DEMO_LIVE
export CASSETTE_MODE=replay
python demo.py | tee /tmp/demo-replay.txt
diff -u /tmp/demo-once.txt /tmp/demo-replay.txt

A second proof is a deliberate miss. Change one character in TICKET under replay. The process must exit non-zero. That miss is the product. Silent fallback to live would reintroduce the original leak.

# expected: cassette miss
CASSETTE_MODE=replay python - <<'PY'
from pathlib import Path
from cassette import Cassette
from live_stub import live_echo
c = Cassette(Path(".cassettes/agent-demo.jsonl"), "replay", live_echo)
c.call({"task": "ticket-summary", "prompt": "different ticket", "max_output_chars": 400})
PY
echo exit:$?

Tests that pin the contract

The test file is short on purpose. It checks hash stability, replay hits, and fail-closed misses. It does not score prose quality.

# test_cassette.py
from pathlib import Path
import pytest
from cassette import Cassette, req_hash

def test_hash_ignores_timestamp():
    a = {"prompt": "x", "timestamp": "2026-09-17T10:00:00Z"}
    b = {"prompt": "x", "timestamp": "2026-09-17T11:00:00Z"}
    assert req_hash(a) == req_hash(b)

def test_replay_hit(tmp_path: Path):
    calls = {"n": 0}
    def live(req):
        calls["n"] += 1
        return {"text": "ok"}
    tape = Cassette(tmp_path / "t.jsonl", "record", live)
    import os
    os.environ["DEMO_LIVE"] = "1"
    assert tape.call({"prompt": "x"})["text"] == "ok"
    os.environ.pop("DEMO_LIVE", None)
    replay = Cassette(tmp_path / "t.jsonl", "replay", live)
    assert replay.call({"prompt": "x"})["text"] == "ok"
    assert calls["n"] == 1

def test_replay_miss_fails_closed(tmp_path: Path):
    tape = Cassette(tmp_path / "t.jsonl", "replay", lambda req: {"text": "nope"})
    with pytest.raises(SystemExit):
        tape.call({"prompt": "missing"})

python -m pytest -q test_cassette.py

If pytest is not installed in the side-project venv, the same assertions can run as a plain script. The weekend cut prefers one green command over a matrix of Python versions.

Where a free model path fits

The cassette is useful without a hosted model. A stub live function is enough to prove the reducer. When the operator needs a real recapture, a hosted path matters because the latch should stay off during the talk and on only for a short recording session.

MonkeyCode is relevant here as one live backend option: free model access and a free server option can recapture a miss without standing up a private GPU box for a Sunday demo. Disclosure: This article was prepared as part of MonkeyCode's product outreach. The cassette still owns the contract. The product does not replace fail-closed replay, and this log does not claim model names, token quotas, hardware sizes, uptime, or permanence.

A practical split looks like this:

Author the prompt and the request schema on Friday night.
Recapture the tape once with CASSETTE_MODE=record and DEMO_LIVE=1.
Commit the JSONL file next to the demo script.
Run Sunday’s walkthrough in replay with the latch unset.

The live path is a recording studio. The committed tape is the demo.

What this weekend skipped

Skipped work is listed so the next weekend does not pretend it already shipped.

No redaction beyond dropping timestamp, request_id, and cwd. Prompts that contain secrets do not belong on this tape.
No file locking. Two parallel recorders will corrupt JSONL.
No schema version field on the cassette itself. A changed canonicalizer is a breaking change; the operator must recapture.
No HTTP capture of an entire provider conversation. Only the dict the agent already built.
No CI job that refreshes tapes on a schedule. Refresh is a human latch, not a cron.
No comparison against prior published gates in this series (write outboxes, step ledgers, spend meters, stdout golden logs). Those remain separate reducers.

Limitations

Replay is not an evaluation harness. A stable tape can still contain a wrong answer. The miss path only proves that the request bytes changed. It does not prove that the response is safe to merge.

The hash is brittle in a useful way. Reordering keys is fine because canonical JSON sorts them. Reordering list items inside the prompt is not fine. That is intended. Silent list normalization would hide prompt drift.

The live stub in this log returns deterministic echo text. A real recapture will not. After recapture, the committed tape is the source of truth, not the provider’s current mood.

Disk is local. Losing .cassettes/ without a commit loses the demo. Treat the JSONL file as source, the same way a fixture is source.

Who should not use this

Skip this cassette when any of the following is true:

The agent mutates customer data or sends mail. Recorded text is not a permit to write. Pair writes with a separate outbox if that is the job.
The prompt may contain tokens, passwords, or private source. JSONL on disk is not a secret store.
The team needs a signed audit trail, retention policy, or multi-writer capture. This file format is a weekend tape, not a compliance log.
The demo must show live streaming UI. This contract stores one finished response object.
The operator wants a quality score for generated code. Hash equality is not a rubric.

For a side project that has to be shown in ten minutes, fail-closed replay is enough. Recapture on a free model path if the tape is empty. Leave the latch off while people watch.

Tape the Model Calls: A Weekend Cassette for Agent Side Projects

Charlie Hu — Thu, 17 Sep 2026 06:27:59 +0000

Scope for one weekend

The cassette owns three jobs. It canonicalizes a model request. It stores one JSON object per hash. It refuses to hit the network unless the operator flips a latch.

Out of scope on purpose:

streaming tokens and partial deltas
provider-specific SDKs and invented model names
encryption at rest or a shared team vault
prompt evals, leaderboards, or quality scores
write side effects against production data

The demo is a CLI that answers a fixed ticket (summarize the failing test) from tape. If the tape misses, the process exits non-zero. That is the whole show.

The failure mode

A cassette does not make the model wiser. It makes the demo honest. Replay is a reducer: same bytes in, same bytes out, or a hard miss.

The cassette contract

The tape is append-only JSONL. Each line is one recorded exchange. The key is a SHA-256 of a canonical request, not a timestamp and not a filename the operator typed by hand.

# layout
.cassettes/
  agent-demo.jsonl

# cassette.py — weekend sketch, not a published library
from __future__ import annotations

import hashlib, json, os
from pathlib import Path
from typing import Any, Callable, Literal

Mode = Literal["replay", "record", "live"]

STRIP = {"timestamp", "request_id", "cwd"}


def canonicalize(req: dict[str, Any]) -> str:
    body = {k: v for k, v in req.items() if k not in STRIP}
    return json.dumps(body, sort_keys=True, separators=(",", ":"), ensure_ascii=False)


def req_hash(req: dict[str, Any]) -> str:
    return hashlib.sha256(canonicalize(req).encode("utf-8")).hexdigest()


class Cassette:
    def __init__(self, path: Path, mode: Mode, live: Callable[[dict[str, Any]], dict[str, Any]]):
        self.path = path
        self.mode = mode
        self.live = live
        self.path.parent.mkdir(parents=True, exist_ok=True)
        self._index = self._load()

    def _load(self) -> dict[str, dict[str, Any]]:
        if not self.path.exists():
            return {}
        out: dict[str, dict[str, Any]] = {}
        for line in self.path.read_text(encoding="utf-8").splitlines():
            if not line.strip():
                continue
            row = json.loads(line)
            out[row["hash"]] = row
        return out

    def call(self, req: dict[str, Any]) -> dict[str, Any]:
        key = req_hash(req)
        if self.mode == "replay":
            if key not in self._index:
                raise SystemExit(f"cassette miss: {key[:12]}")
            return self._index[key]["response"]
        if self.mode == "record" and key in self._index:
            return self._index[key]["response"]
        if self.mode != "live" and os.environ.get("DEMO_LIVE") != "1":
            raise SystemExit("live latch is off; set DEMO_LIVE=1 to recapture")
        response = self.live(req)
        row = {"hash": key, "request": json.loads(canonicalize(req)), "response": response}
        with self.path.open("a", encoding="utf-8") as fh:
            fh.write(json.dumps(row, ensure_ascii=False) + "\n")
        self._index[key] = row
        return response

Replay never calls live. Record reuses a hit and only captures a miss when the latch is on. Live always captures. Those three sentences are the contract. Everything else is ceremony.

A stub live function, labeled as a stub

The weekend build does not ship a vendor client. The live function is an injected callable so the cassette stays testable without inventing endpoints, model names, or quotas.

# live_stub.py — example only; replace with a real client in the operator’s repo

def live_echo(req: dict) -> dict:
    prompt = req["prompt"]
    return {
        "text": f"STUB:{prompt[:80]}",
        "usage": {"input_chars": len(prompt), "output_chars": 0},
    }

When a real client exists, it should return a JSON-serializable dict and nothing else. Binary blobs and iterator streams are skipped this weekend. They break the tape format.

Tiny agent loop

The agent is a function, not a platform. It builds one request, asks the cassette, and prints one line. No tool loop. No retries. No hidden second call.

# demo.py
import os
from pathlib import Path
from cassette import Cassette
from live_stub import live_echo

TICKET = "summarize the failing test: test_invoice_total"

def build_request(ticket: str) -> dict:
    return {
        "task": "ticket-summary",
        "prompt": ticket,
        "max_output_chars": 400,
    }

def main() -> None:
    mode = os.environ.get("CASSETTE_MODE", "replay")
    tape = Cassette(Path(".cassettes/agent-demo.jsonl"), mode, live_echo)  # type: ignore[arg-type]
    text = tape.call(build_request(TICKET))["text"]
    print(text)

if __name__ == "__main__":
    main()

Third-person rule for the demo script: the operator exports mode, runs the file, and reads stdout. No dashboard. No spinner. The golden path is replay.

Commands that prove the demo

Capture once, with the latch on. Then freeze the tape and turn the latch off.

mkdir -p .cassettes
export CASSETTE_MODE=record
export DEMO_LIVE=1
python demo.py | tee /tmp/demo-once.txt

unset DEMO_LIVE
export CASSETTE_MODE=replay
python demo.py | tee /tmp/demo-replay.txt
diff -u /tmp/demo-once.txt /tmp/demo-replay.txt

# expected: cassette miss
CASSETTE_MODE=replay python - <<'PY'
from pathlib import Path
from cassette import Cassette
from live_stub import live_echo
c = Cassette(Path(".cassettes/agent-demo.jsonl"), "replay", live_echo)
c.call({"task": "ticket-summary", "prompt": "different ticket", "max_output_chars": 400})
PY
echo exit:$?

Tests that pin the contract

The test file is short on purpose. It checks hash stability, replay hits, and fail-closed misses. It does not score prose quality.

# test_cassette.py
from pathlib import Path
import pytest
from cassette import Cassette, req_hash

def test_hash_ignores_timestamp():
    a = {"prompt": "x", "timestamp": "2026-09-17T10:00:00Z"}
    b = {"prompt": "x", "timestamp": "2026-09-17T11:00:00Z"}
    assert req_hash(a) == req_hash(b)

def test_replay_hit(tmp_path: Path):
    calls = {"n": 0}
    def live(req):
        calls["n"] += 1
        return {"text": "ok"}
    tape = Cassette(tmp_path / "t.jsonl", "record", live)
    import os
    os.environ["DEMO_LIVE"] = "1"
    assert tape.call({"prompt": "x"})["text"] == "ok"
    os.environ.pop("DEMO_LIVE", None)
    replay = Cassette(tmp_path / "t.jsonl", "replay", live)
    assert replay.call({"prompt": "x"})["text"] == "ok"
    assert calls["n"] == 1

def test_replay_miss_fails_closed(tmp_path: Path):
    tape = Cassette(tmp_path / "t.jsonl", "replay", lambda req: {"text": "nope"})
    with pytest.raises(SystemExit):
        tape.call({"prompt": "missing"})

python -m pytest -q test_cassette.py

If pytest is not installed in the side-project venv, the same assertions can run as a plain script. The weekend cut prefers one green command over a matrix of Python versions.

Where a free model path fits

A practical split looks like this:

Author the prompt and the request schema on Friday night.
Recapture the tape once with CASSETTE_MODE=record and DEMO_LIVE=1.
Commit the JSONL file next to the demo script.
Run Sunday’s walkthrough in replay with the latch unset.

The live path is a recording studio. The committed tape is the demo.

What this weekend skipped

Skipped work is listed so the next weekend does not pretend it already shipped.

No redaction beyond dropping timestamp, request_id, and cwd. Prompts that contain secrets do not belong on this tape.
No file locking. Two parallel recorders will corrupt JSONL.
No schema version field on the cassette itself. A changed canonicalizer is a breaking change; the operator must recapture.
No HTTP capture of an entire provider conversation. Only the dict the agent already built.
No CI job that refreshes tapes on a schedule. Refresh is a human latch, not a cron.
No comparison against prior published gates in this series (write outboxes, step ledgers, spend meters, stdout golden logs). Those remain separate reducers.

Limitations

Replay is not an evaluation harness. A stable tape can still contain a wrong answer. The miss path only proves that the request bytes changed. It does not prove that the response is safe to merge.

The live stub in this log returns deterministic echo text. A real recapture will not. After recapture, the committed tape is the source of truth, not the provider’s current mood.

Disk is local. Losing .cassettes/ without a commit loses the demo. Treat the JSONL file as source, the same way a fixture is source.

Who should not use this

Skip this cassette when any of the following is true:

The agent mutates customer data or sends mail. Recorded text is not a permit to write. Pair writes with a separate outbox if that is the job.
The prompt may contain tokens, passwords, or private source. JSONL on disk is not a secret store.
The team needs a signed audit trail, retention policy, or multi-writer capture. This file format is a weekend tape, not a compliance log.
The demo must show live streaming UI. This contract stores one finished response object.
The operator wants a quality score for generated code. Hash equality is not a rubric.

For a side project that has to be shown in ten minutes, fail-closed replay is enough. Recapture on a free model path if the tape is empty. Leave the latch off while people watch.

Permit the Writes: A Weekend Outbox for Agent Side Projects

Charlie Hu — Wed, 16 Sep 2026 04:25:29 +0000

Weekend agent demos break when the model can mutate the working tree while it is still exploring. A small permit file and an on-disk outbox keep exploration cheap and commits explicit. The demo is not a longer chat. It is one flushed write that a test can reject.

This note is a weekend build log, not a platform review. Scope was cut first. The working path is a permit desk. Everything else was skipped on purpose.

The failure that wastes Saturday

Side-project agents do not usually fail on the first prompt. They fail on the third retry, when a “fix the demo” turn rewrites README.md, a config file, and a test in the same breath. The transcript still looks productive. The tree does not.

Read-only turns are cheap. Writes are the scarce resource. A weekend kit should treat them that way.

Recent public debate around “vibe coding” versus engineering is noisy. The practical split on a laptop is smaller. If a tool call can change disk, it needs a permit. If it cannot, it can loop until the clock runs out.

Scope cut for one weekend

The build kept three jobs and deleted the rest.

Load a static allowlist of write paths from the repo.
Catch attempted writes and append them to outbox.jsonl instead of touching the tree.
Flush one approved record through a command that a test can run twice.

Skipped on Saturday: multi-user auth, cloud queues, model routing, token dashboards, and any claim about which model is “best.” Those inflate the demo. They do not prove the permit.

The artifact is one Python module, one permit file, one test, and a short shell path. That is the whole ship.

The permit file

The allowlist is boring on purpose. Boring files survive a weekend.

{
  "version": 1,
  "demo_id": "weekend-outbox-001",
  "write_roots": ["demo_out/"],
  "max_flush": 1,
  "forbidden_globs": [
    ".git/**",
    "**/*secret*",
    "**/.env",
    "permits.json"
  ]
}

write_roots is the only place a flush may land. forbidden_globs is a hard veto even if a model argues. max_flush is the Saturday halt: one committed file, then stop. The agent may propose many writes. The desk keeps one.

The outbox desk

The module below is a complete, runnable sketch. It does not call a network model. It only gates writes. Label it as a local fixture, not a production agent runtime.

#!/usr/bin/env python3
"""permit_desk.py — catch writes, flush one permitted path."""
from __future__ import annotations

import json
import re
from dataclasses import dataclass
from datetime import datetime, timezone
from pathlib import Path
from typing import Any

ROOT = Path(__file__).resolve().parent
PERMIT_PATH = ROOT / "permits.json"
OUTBOX_PATH = ROOT / "outbox.jsonl"
FLUSHED_PATH = ROOT / "flushed.json"


@dataclass(frozen=True)
class Permit:
    version: int
    demo_id: str
    write_roots: tuple[str, ...]
    max_flush: int
    forbidden_globs: tuple[str, ...]


def load_permit(path: Path = PERMIT_PATH) -> Permit:
    raw = json.loads(path.read_text(encoding="utf-8"))
    return Permit(
        version=int(raw["version"]),
        demo_id=str(raw["demo_id"]),
        write_roots=tuple(raw["write_roots"]),
        max_flush=int(raw["max_flush"]),
        forbidden_globs=tuple(raw["forbidden_globs"]),
    )


def _is_forbidden(rel: str, permit: Permit) -> bool:
    text = rel.replace("\\", "/")
    for glob in permit.forbidden_globs:
        pattern = re.escape(glob).replace("\\*\\*", ".*").replace("\\*", "[^/]*")
        if re.fullmatch(pattern, text):
            return True
    return False


def _under_root(rel: str, permit: Permit) -> bool:
    text = rel.replace("\\", "/")
    return any(text.startswith(root) for root in permit.write_roots)


def propose_write(relpath: str, content: str, permit: Permit | None = None) -> dict[str, Any]:
    permit = permit or load_permit()
    rel = relpath.replace("\\", "/")
    record = {
        "ts": datetime.now(timezone.utc).isoformat(),
        "demo_id": permit.demo_id,
        "relpath": rel,
        "bytes": len(content.encode("utf-8")),
        "content": content,
        "status": "queued",
    }
    if _is_forbidden(rel, permit) or not _under_root(rel, permit):
        record["status"] = "rejected"
        record["reason"] = "path not permitted"
    OUTBOX_PATH.parent.mkdir(parents=True, exist_ok=True)
    with OUTBOX_PATH.open("a", encoding="utf-8") as handle:
        handle.write(json.dumps(record, ensure_ascii=False) + "\n")
    return record


def flush_one(permit: Permit | None = None) -> dict[str, Any]:
    permit = permit or load_permit()
    if FLUSHED_PATH.exists():
        raise SystemExit("demo already flushed; refuse second write")
    if not OUTBOX_PATH.exists():
        raise SystemExit("outbox empty")

    queued = []
    for line in OUTBOX_PATH.read_text(encoding="utf-8").splitlines():
        if not line.strip():
            continue
        item = json.loads(line)
        if item.get("status") == "queued":
            queued.append(item)
    if not queued:
        raise SystemExit("no queued writes")
    if permit.max_flush != 1:
        raise SystemExit("this weekend kit flushes exactly one record")

    chosen = queued[0]
    target = ROOT / chosen["relpath"]
    target.parent.mkdir(parents=True, exist_ok=True)
    target.write_text(chosen["content"], encoding="utf-8")
    chosen["status"] = "flushed"
    FLUSHED_PATH.write_text(json.dumps(chosen, indent=2), encoding="utf-8")
    return chosen

The important behavior is negative. A rejected path still lands in the outbox. It never lands in demo_out/. The Saturday operator reads the log, not the model’s self-report.

A test that fails before the demo

The kit is not real until a test refuses a write the agent would love to make.

# test_permit_desk.py
from pathlib import Path
import json
import permit_desk as desk


def test_rejects_git_and_env(tmp_path, monkeypatch):
    monkeypatch.chdir(tmp_path)
    (tmp_path / "permits.json").write_text(json.dumps({
        "version": 1,
        "demo_id": "t",
        "write_roots": ["demo_out/"],
        "max_flush": 1,
        "forbidden_globs": [".git/**", "**/.env"],
    }))
    monkeypatch.setattr(desk, "ROOT", tmp_path)
    monkeypatch.setattr(desk, "PERMIT_PATH", tmp_path / "permits.json")
    monkeypatch.setattr(desk, "OUTBOX_PATH", tmp_path / "outbox.jsonl")
    monkeypatch.setattr(desk, "FLUSHED_PATH", tmp_path / "flushed.json")

    bad = desk.propose_write(".env", "TOKEN=nope")
    assert bad["status"] == "rejected"
    assert not Path(".env").exists()

    good = desk.propose_write("demo_out/hello.txt", "ok\n")
    assert good["status"] == "queued"
    flushed = desk.flush_one()
    assert flushed["relpath"] == "demo_out/hello.txt"
    assert (tmp_path / "demo_out/hello.txt").read_text() == "ok\n"

Run it locally:

python3 -m pip install pytest
python3 -m pytest -q test_permit_desk.py

The demo is the failing case as much as the passing one. If .env can be written, the weekend is already over.

Commands that prove one path

A short shell path is the public artifact. Chat logs are not.

python3 - <<'PY'
from permit_desk import propose_write, flush_one
print(propose_write("README.md", "# hijack\n"))
print(propose_write("demo_out/receipt.txt", "demo ok\n"))
print(flush_one())
PY

cat outbox.jsonl
cat flushed.json
cat demo_out/receipt.txt
test ! -f README.md

Expected shape of outbox.jsonl:

{"relpath": "README.md", "status": "rejected", "reason": "path not permitted"}
{"relpath": "demo_out/receipt.txt", "status": "queued"}

After flush, README.md is still absent. demo_out/receipt.txt exists. A second flush_one() exits non-zero. That second failure is part of the demo. It records the skip: no extra writes after the receipt.

Decision table for Saturday

Attempted path	Permit result	Disk effect
`demo_out/receipt.txt`	queued, then one flush	file created
`README.md`	rejected	unchanged
`.env`	rejected	unchanged
`.git/config`	rejected	unchanged
second flush	process exit	no extra file

The table is the product. Models can narrate. The table cannot.

Where a free remote host fits

The permit file has to travel with the repo. A local laptop and a remote workspace should load the same permits.json. If the host changes and the allowlist does not, the agent has been given a new machine without a new contract.

Disclosure: This article was prepared as part of MonkeyCode's product outreach. MonkeyCode’s free model access and free server option can host that same layout so the permit desk is not tied to one laptop. No model names, quotas, or hardware claims are attached here because they are not needed to run the fixture. The desk still refuses .env if the process is far away.

Readers who already have a box can ignore the host and keep the files. The workflow does not depend on a vendor remaining available.

What this weekend skipped

Skipped items were written down so they do not sneak back in as “small refactors.”

No retry budget. The step count is a different kit.
No spend meter. Token cost is a different kit.
No golden stdout log. The receipt is a file on disk, not a captured stream.
No merge gate for generated patches. Flush is not a pull request.
No attempt to rank models. The allowlist does not care who proposed the write.

Those skips are features of the Saturday. A demo that also measures cost, steps, and model quality is no longer a demo. It is a platform.

Limits

The glob matcher is a short regex stand-in. It is not a full gitignore engine. Symbolic links, case-folded filesystems, and writes through subprocesses that never call propose_write will bypass it. The desk is an honor system plus a test, not a kernel sandbox.

max_flush is a file flag, not a distributed lock. Two shells can race. That is acceptable for a weekend side project. It is not acceptable for a shared production volume.

The outbox stores full file contents in JSONL. Large binaries do not belong there. Text receipts do.

Who should not use this approach

Teams with a real sandbox, mandatory code review, or existing policy engines do not need a JSON allowlist. People shipping secrets, payments, or medical data should not treat an outbox file as isolation. Operators who want a ranked model bake-off will not find one in this log.

The kit is for a single maintainer who already let an agent wander through a repo once and did not like the diff. It restores a boring rule: reads may loop, writes need a permit, and the weekend ends after one flushed path.

Preflight the Free Allowance: A Weekend Spend Meter for Agent Side Projects

Charlie Hu — Mon, 14 Sep 2026 21:53:50 +0000

Preflight the Free Allowance: A Weekend Spend Meter for Agent Side Projects

Most weekend agent builds do not fail on code quality. They fail on arithmetic.

A loop that looks cheap per call keeps calling until the allowance is gone, and the build stops on Sunday night with half a checklist left. The DEV front page spent the week on arguments about what agents really are and whether AI-written code deserves the engineering label. Neither argument changes the arithmetic of a two-day project.

The fix is small and unglamorous: measure the spend before the expensive run, not after it. This build log covers one file that does that, the scope it cut, and the parts it deliberately skips.

The three numbers worth writing down

Token accounting for a side project needs exactly three quantities.

Planned calls per run. A list of named steps, each with a rough token estimate.
Observed tokens per call. Prompt plus completion, read from the provider's usage field after each call.
Retries per call. The multiplier nobody budgets for. Three retries on a 6k-token step is an 18k-token step.

Anything beyond those three belongs in provider billing, not in a weekend script. The goal here is a preflight check, not an invoice.

The artifact: `meter.py`

One file, standard library only, two modes: read recorded events, or evaluate a plan worst case. Exit code 1 means over allowance, 2 means the event log is corrupt.

#!/usr/bin/env python3
"""meter.py - preflight and postflight token accounting for a weekend agent demo.

Usage:
  python meter.py --events runs/sat.jsonl --allowance 10000000
  python meter.py --plan plan.json --allowance 10000000
Exit codes: 0 under allowance, 1 over, 2 malformed event lines.
"""
from __future__ import annotations

import argparse
import json
import sys
from pathlib import Path

MALFORMED_TOLERANCE = 0  # any unparsable line fails the run


def read_events(path: Path) -> tuple[list[dict], int]:
    events: list[dict] = []
    malformed = 0
    for raw in path.read_text(encoding="utf-8").splitlines():
        raw = raw.strip()
        if not raw:
            continue
        try:
            ev = json.loads(raw)
            events.append(
                {
                    "call": str(ev["call"]),
                    "prompt_tokens": int(ev.get("prompt_tokens", 0)),
                    "completion_tokens": int(ev.get("completion_tokens", 0)),
                    "retries": int(ev.get("retries", 0)),
                }
            )
        except (json.JSONDecodeError, KeyError, TypeError, ValueError):
            malformed += 1
    return events, malformed


def spend(events: list[dict]) -> tuple[int, dict[str, int]]:
    per_call: dict[str, int] = {}
    total = 0
    for ev in events:
        n = ev["prompt_tokens"] + ev["completion_tokens"]
        per_call[ev["call"]] = per_call.get(ev["call"], 0) + n
        total += n
    return total, per_call


def worst_case(plan: dict) -> int:
    retries = int(plan.get("max_retries", 0))
    return sum(int(c["est_tokens"]) * (1 + retries) for c in plan["calls"])


def main() -> int:
    ap = argparse.ArgumentParser()
    ap.add_argument("--events", type=Path)
    ap.add_argument("--plan", type=Path)
    ap.add_argument("--allowance", type=int, required=True)
    args = ap.parse_args()

    if not args.events and not args.plan:
        ap.error("pass --events, --plan, or both")

    if args.events:
        events, malformed = read_events(args.events)
        if malformed > MALFORMED_TOLERANCE:
            print(f"MALFORMED: {malformed} unparsable event lines")
            return 2
        total, per_call = spend(events)
        print(f"observed {total:,} tokens across {len(events)} calls")
        for name, n in sorted(per_call.items(), key=lambda kv: -kv[1]):
            print(f"  {name:<24} {n:>12,}")
        if total > args.allowance:
            print(f"OVER: observed spend exceeds allowance {args.allowance:,}")
            return 1

    if args.plan:
        plan = json.loads(args.plan.read_text(encoding="utf-8"))
        ceiling = worst_case(plan)
        headroom = args.allowance - ceiling
        print(f"worst case {ceiling:,} | allowance {args.allowance:,} | headroom {headroom:,}")
        if headroom < 0:
            print("OVER: cut a call or lower max_retries before the batch")
            return 1

    return 0


if __name__ == "__main__":
    sys.exit(main())

The plan file is a plain description of the intended run:

{
  "max_retries": 2,
  "calls": [
    {"name": "summarize_repo", "est_tokens": 3000},
    {"name": "draft_patch", "est_tokens": 6000},
    {"name": "self_review", "est_tokens": 4000}
  ]
}

$ python meter.py --plan plan.json --allowance 10000000
worst case 39,000 | allowance 10,000,000 | headroom 9,961,000

The numbers above are illustrative, not a benchmark. The point is the shape of the output: a single headroom figure that either passes or stops the batch.

Recording one event per call

Metering only works if every call writes a line. A six-line helper is enough; the field names come from the provider's usage object and differ between providers, so map them once and keep the mapping in the repo.

import json
import time


def record(path, name, usage, retries=0):
    with open(path, "a", encoding="utf-8") as fh:
        fh.write(json.dumps({
            "ts": time.time(),
            "call": name,
            "prompt_tokens": getattr(usage, "prompt_tokens", 0),
            "completion_tokens": getattr(usage, "completion_tokens", 0),
            "retries": retries,
        }) + "\n")

Two rules keep the log trustworthy. Append after the call returns, so a crash does not record phantom spend. And log retries explicitly, because a retry count of zero is information too.

Where the batch actually runs

The meter answers how much. A separate question is where the calls go, especially for a batch that runs overnight.

MonkeyCode is one option for that second question: the operator states free model access and a free server option, and quotes a free allowance on the order of ten million tokens. Disclosure: This article was prepared as part of MonkeyCode's product outreach. Because meter.py only consumes JSONL, the same accounting works whether the calls hit a local mock or a hosted endpoint; only the field mapping changes. Treat the allowance figure, the available models, and the server option as operator-supplied claims that can change, and re-read the current terms before planning a weekend around them.

If the spend meter is the useful part of this post, start there. Run one real batch inside the free tier only after checking today's terms, not last month's.

Decision table

Situation	Local run	Remote free tier	Skip the call
One short call, you are watching the output	Yes	Unnecessary	No
Batch that runs while you sleep	Works, ties up your laptop	Candidate - verify terms first	Only if you cannot judge the output tomorrow
Retry storm already observed in the log	Yes	No - fix the prompt first	Yes, until retries are controlled
Output you cannot evaluate tonight	No	No	Yes
Anything closer to production than a demo	Budget alerts, not this script	Same	Change the project

What this build skipped on purpose

A weekend scope is defined by what is not built. Three cuts made the file small enough to finish.

No dashboard. A printed table and an exit code are the whole interface.
No price conversion. Tokens are the unit; currency changes with provider and date, and static prices rot.
No automatic throttling. The script reports and exits. A wrapper that silently trims prompts is a second project.

Limitations and who should not use this

Token counts come from provider usage fields. Some providers round them, and cached-input accounting differs, so this is a spend estimate, not a billing statement.
The max_retries multiplier in plan.json is a guess until it is calibrated against recorded events. Two weekends of real logs beat any estimate.
The meter says nothing about quality. A cheap call that returns unusable output is the most expensive item in the plan.
Free-tier availability, quotas, model line-ups, and server options are commercial terms, not technical constants. Nothing in meter.py depends on them staying the same.
Teams needing billing-grade cost allocation, multi-tenant chargeback, or audit trails should use provider-side budgets and alerts. So should anyone whose calls are not token-metered at all.

Sunday check

Before the demo is called done, five things are worth confirming.

python meter.py --events runs/sun.jsonl --allowance ... exits 0.
Every planned call in plan.json has a matching entry in the event log.
The retry multiplier in the plan matches the retries actually seen in the log.
The skipped calls are written down somewhere, with the reason.
The current free-tier terms were read this weekend, not remembered from an older post.

The demo proves the idea. The meter keeps the next weekend from being spent re-learning the same arithmetic.

Keep the Agent Finite: A Weekend Step Ledger for Side Projects

Charlie Hu — Sun, 13 Sep 2026 20:40:02 +0000

Weekend agent builds rarely die from a missing feature. They die from an unbounded loop that reopens every skipped path. A local step ledger with a hard maximum, an allowlisted tool set, and a closed skip column keeps the demo finite even when generation runs on another machine.

The rest of this note is a proposed weekend kit. It is not a production agent framework and it is not a benchmark.

Cut the loop, not the repository

A side project has two scopes. Feature scope is the list of files the demo may touch. Loop scope is the number of tool steps the agent may take before the weekend is over.

Feature scope is the usual cut. Loop scope is the one that actually burns the Saturday. An agent that can still inspect one more file will inspect twenty.

The ledger below treats loop scope as the primary budget. Eight steps is a default, not a law. The number is small on purpose. A demo that needs forty tool calls is not a weekend demo.

What "done" means this weekend

The working demo is a single command with a frozen expected line on stdout. No UI. No extra endpoints. No README rewrite.

Proposed demo contract:

Command: python demo.py
Expected stdout: ok: greeter ready
Allowed files: demo.py, tests/test_demo.py, loop_ledger.json
Forbidden: new dependencies, git push, refactors outside the allowlist

Anything else goes in the skip column with a reason code. The next prompt is not allowed to reopen a skip without a human edit to the ledger.

The ledger file

Keep the ledger in git. The model may append steps. The model may not raise max_steps, may not delete skips, and may not expand allowed_files.

{
  "goal": "demo.py prints a frozen greeting and tests/test_demo.py asserts it",
  "max_steps": 8,
  "allowed_tools": ["read_file", "write_file", "run_cmd"],
  "allowed_files": ["demo.py", "tests/test_demo.py", "loop_ledger.json"],
  "allowed_cmds": ["python demo.py", "python -m pytest tests/test_demo.py -q"],
  "steps": [],
  "skips": [
    {
      "id": "S1",
      "item": "HTTP server and /health route",
      "reason": "out_of_demo"
    },
    {
      "id": "S2",
      "item": "config file and env loader",
      "reason": "out_of_demo"
    },
    {
      "id": "S3",
      "item": "retry/backoff helper",
      "reason": "reopens_loop"
    }
  ],
  "status": "open"
}

Reason codes stay short. out_of_demo means the item is real work for another weekend. reopens_loop means the item would invite more tool calls than the budget. needs_human means the agent must stop rather than guess.

A tiny runner

The runner is ordinary Python. It does not call a model. It only enforces the ledger so a coding agent, or a tired human, cannot spend the budget on "one more step."

# loop_ledger.py
# Proposed weekend fixture. Not a production orchestrator.
from __future__ import annotations

import json
import subprocess
import sys
from pathlib import Path

LEDGER = Path("loop_ledger.json")
CLOSED_REASONS = {"out_of_demo", "reopens_loop", "needs_human"}


def load() -> dict:
    data = json.loads(LEDGER.read_text(encoding="utf-8"))
    data.setdefault("steps", [])
    data.setdefault("skips", [])
    return data


def save(data: dict) -> None:
    LEDGER.write_text(json.dumps(data, indent=2) + "\n", encoding="utf-8")


def assert_open(data: dict) -> None:
    if data.get("status") == "closed":
        raise SystemExit("ledger is closed; demo is frozen")
    if len(data["steps"]) >= int(data["max_steps"]):
        raise SystemExit("max_steps reached; record a skip or stop")


def record_step(tool: str, target: str, note: str) -> None:
    data = load()
    assert_open(data)
    if tool not in data["allowed_tools"]:
        raise SystemExit(f"tool not allowed: {tool}")
    if tool in {"read_file", "write_file"} and target not in data["allowed_files"]:
        raise SystemExit(f"file not allowed: {target}")
    if tool == "run_cmd" and target not in data["allowed_cmds"]:
        raise SystemExit(f"cmd not allowed: {target}")
    data["steps"].append({"tool": tool, "target": target, "note": note})
    save(data)
    print(f"step {len(data['steps'])}/{data['max_steps']} {tool} {target}")


def add_skip(item: str, reason: str) -> None:
    data = load()
    if reason not in CLOSED_REASONS:
        raise SystemExit(f"unknown skip reason: {reason}")
    next_id = f"S{len(data['skips']) + 1}"
    data["skips"].append({"id": next_id, "item": item, "reason": reason})
    save(data)
    print(f"skip {next_id} {reason}")


def close_if_demo_passes() -> None:
    data = load()
    result = subprocess.run(
        [sys.executable, "-m", "pytest", "tests/test_demo.py", "-q"],
        check=False,
    )
    if result.returncode != 0:
        raise SystemExit("demo tests failed; ledger stays open")
    data["status"] = "closed"
    save(data)
    print("demo passed; ledger closed")


def main(argv: list[str]) -> None:
    if len(argv) < 2:
        raise SystemExit("usage: record|skip|close ...")
    cmd = argv[1]
    if cmd == "record" and len(argv) == 5:
        record_step(argv[2], argv[3], argv[4])
        return
    if cmd == "skip" and len(argv) == 4:
        add_skip(argv[2], argv[3])
        return
    if cmd == "close":
        close_if_demo_passes()
        return
    raise SystemExit("usage: record|skip|close ...")


if __name__ == "__main__":
    main(sys.argv)

Commands stay boring on purpose:

python loop_ledger.py record write_file demo.py "print frozen greeting"
python loop_ledger.py record write_file tests/test_demo.py "assert stdout"
python loop_ledger.py record run_cmd "python -m pytest tests/test_demo.py -q" "prove demo"
python loop_ledger.py skip "add FastAPI /health" out_of_demo
python loop_ledger.py close

If a step is rejected, that is the product. The rejection is the scope cut.

The two files the demo may touch

# demo.py
def greeting() -> str:
    return "ok: greeter ready"


if __name__ == "__main__":
    print(greeting())

# tests/test_demo.py
import subprocess
import sys
from pathlib import Path

ROOT = Path(__file__).resolve().parents[1]


def test_demo_stdout_is_frozen():
    proc = subprocess.run(
        [sys.executable, str(ROOT / "demo.py")],
        check=True,
        capture_output=True,
        text=True,
    )
    assert proc.stdout.strip() == "ok: greeter ready"

The test pins stdout. A later agent that "improves" the copy will fail closed. That failure is cheaper than arguing with a chat log on Sunday night.

A worked Saturday sequence

Start with an empty steps array and the three skips already filled. The first records are reads. They cost budget. Reading is not free in this kit, because unbounded read_file is how loops pretend to be research.

Proposed sequence:

record read_file demo.py — observe the file is missing.
record write_file demo.py — add greeting().
record write_file tests/test_demo.py — freeze stdout.
record run_cmd for pytest — fail because the print has a trailing period.
record write_file demo.py — match the frozen line.
record run_cmd for pytest — pass.
skip "extract a Greeter class" reopens_loop.
close.

Two steps remain unused. Unused steps are not a dare. They are leftover budget. Closing the ledger spends them on nothing, which is the correct spend.

The runner cannot parse intent inside a file. A write to demo.py that quietly starts a web server would still record if the path is allowlisted. The skip column and the frozen stdout test are the backstop, and they are incomplete on purpose. Honesty about that gap belongs in the weekend log.

Decision table for skips

Candidate change	Ledger action	Reason code
Extra CLI flag that the demo command never uses	skip	`out_of_demo`
New dependency to make the greeting nicer	skip	`reopens_loop`
Refactor into a package with `__init__`	skip	`reopens_loop`
Ambiguous product copy	skip	`needs_human`
Fix the frozen greeting so the test passes	`record_step`	in budget
Add a test that asserts the same line	`record_step`	in budget

The table is the weekend policy. The agent does not get a parallel policy in a system prompt that contradicts it.

Prompt text that defers to the ledger

Proposed system fragment. Unexecuted. Paste it next to the repo. Do not treat it as an evaluated prompt.

You may only change files in allowed_files.
Before any extra feature, add a skip with reason out_of_demo or reopens_loop.
If max_steps is reached, stop. Do not ask to raise it.
Do not implement any item already in skips.

Four lines. The ledger is the source of truth. The prompt is a pointer.

Where generation can run

The ledger is local. The generator does not have to be.

Disclosure: This article was prepared as part of MonkeyCode's product outreach.

A laptop that is already compiling tests does not also need to host a long coding session. MonkeyCode's free model access and free server option can run the generator while loop_ledger.json stays in the repo and keeps rejecting out-of-scope tool calls. The interesting part is still the ledger. Remove the remote session and the same budget still applies.

If that remote option is already in reach, point the agent at the two allowed files and the commands above. Do not raise max_steps because the session is free. A free loop with no cap is still an unbounded loop.

What this weekend skips on purpose

No streaming UI for token traces.
No multi-agent debate over the greeting.
No prompt store, vector index, or memory layer.
No automatic reopen of S1–S3 when tests pass early.

Those skips are the build. A closed ledger with three skips and a green demo is a finished weekend. An open ledger with an almost-working HTTP stack is not.

Limitations

The kit does not measure model quality. It does not stop a determined editor from changing max_steps by hand. It does not replace code review, secret scanning, or a real merge gate.

JSON is not a workflow engine. Concurrent agents will clobber the ledger. There is no file locking in the script above.

Stdout matching is brittle on purpose. It will reject useful changes that alter the greeting. That is the point for a weekend freeze. It is the wrong tool for a product that must evolve copy every day.

The allowlist is path-based, not AST-based. Scope still depends on a human who will not "just" expand allowed_files at 11 p.m.

Who should not use this

Teams shipping production agents with real users or compliance needs.
Exploratory research whose goal is to watch the model wander.
Anyone who needs the agent to add dependencies or touch infrastructure.
Builders who will not keep the skip column honest.

A finite loop is a constraint. Constraints only help when the demo is small enough to finish.

The next weekend can open a new ledger. It should not reopen this one.