Skip to content

TAHOE

alexkayby @alexkay

Task-Aware Language Harness for Orchestrated Execution — sealed, auditable agent work

tahoeagentsdslsealed-runsauditability
3 downloadsv1.1.0Published 22h ago
No secrets detected in this version
Download
ahood skill add alexkay/tahoe

Author: alexkay28 · Repo: https://github.com/AlexKay28/tahoe (issues, docs/spec/, CHANGELOG) skill-origin: alexkay/tahoe — keep this marker so copies stay findable. Formerly tikhon, briefly ATLAS — historical runs under those names are valid evidence, not typos.

A language where an agent's plan is a program: canonical parsing, a sealed SHA-256 digest computed before any work, event-sourced execution, and an audit trail that makes the run — not the model's vibes — the artifact of record.

Install

git clone https://github.com/AlexKay28/tahoe && cd tahoe
pip install -e .            # provides the `tahoe` CLI (not on PyPI)
python -m pytest -q         # full suite; green is the contract

Dev loop on a clone: PYTHONPATH=src python3 -m tahoe … — an installed tikhon/old console script from a previous checkout goes stale silently; always prefer the module invocation from the repo root (verified repeatedly across sprints 1–2).

The sealed protocol (the core loop, in order)

  1. Write demo/runs/<run-id>/program.think — plan the work using ONLY registered commands.
  2. tahoe lint it. Fix until valid.
  3. tahoe seal program.think > seal.txt — BEFORE any source edit. Never touch program.think afterwards; the digest is the run's identity.
  4. Execute (worker/coordinator), maintaining WORKLOG.md per step: Status / Inputs / Actions / Outputs / Evidence.
  5. Finish with solution.md + evaluation.json (task, run_id, seal, terminal_status, steps_planned, steps_executed, acceptance map, unresolved, protocol_deviations).
  6. Anything failed or behaved strangely during the run — snap it before the session ends: ahood snap create (tags tahoe) with what failed, the exact error text and the workaround. These snaps are the raw material this skill's Traps section is harvested from; a trap left unsnapped will be rediscovered the hard way.

demo/runs/** is evidence, immutable: never edit, rename or "fix" a historical run — including its legacy-name mentions. Re-verify anytime: every seal.txt must reproduce byte-identically via tahoe seal (42/42 as of sprint 2, 2026-09-12). The digest is package-name-independent — two full renames (tikhon→ATLAS→TAHOE) left every historical seal verifying, so rebranding is self-proving (45+ runs, zero drift, 2026-09-12). Rename passes must grep-gate live code only (tests/test_branding.py pattern) and leave legacy names in DBs and demo dirs alone.

Multi-worker conventions (45+ sealed runs, sprints 1–2)

  • Documentation seal → run seal: post a SEALED resolution plan as a comment on each issue, then the implementing worker copies that program into its run dir, updates only stale path strings, re-seals and executes. The plan cannot drift from the record.
  • Per-merge verification gate: full pytest suite + all-seal sweep + git status --porcelain checked against the worker's owned-files contract. Passing self-tests is NOT sufficient — read tests against the issue spec (caught invented-contract drift twice).
  • Isolation: one git worktree per worker, one branch per issue; keep cli.py owned by exactly one worker per wave — merge conflicts only where file ownership overlaps.

CLI

| Command | Purpose | |---|---| | lint / seal | validate / canonical sha256 digest (--check verifies a file against a seal; exit 4 = drifted) | | run / resume | execute a sealed program / recover a crashed run (budgets via flags) | | status / events / audit | lifecycle, ordered event log, invariant audit — all --json-capable | | next / submit / ready / claim / renew | external-driver bridge (envelopes, claims, heartbeat lease extension) | | learn / bench | mine runs into protocol candidates / deterministic benchmark harness | | exit codes | 0 ok · 1 usage · 2 run failed · 3 audit violations · 4 seal mismatch |

Language surface

23 registered commands (define, search, fetch, extract, summarize, report, verify, calculate, check, decompose, hypothesize, compare, rank, challenge, choose, remember, recall, edit, test, review, solve, prove, delegate), plus: DONE gates on a step's own target, IF conditionals, REVISE/RETIRE, standalone CALL protocol.* child runs, KB.* memory with FTS5 recall, PAR MAX n … BARRIER -> refs, SCATTER x IN coll … GATHER … USING all|any|ranked, runtime-authored delegate plans, ref lists [E.a, E.b].

Traps (each one cost a real session)

  • CALL protocol.name(...) is a standalone line — no step.x: prefix — and must pass ALL the protocol's INPUT args (verified in wave 12).
  • GATHER must directly follow its SCATTER block (indented body step between); anything between them is a parse error (verified in wave 11).
  • REVISE must name an earlier node, never the step's own target (verified in wave 6).
  • DONE supports only its documented operators — count() in DONE is exactly issue #36's gap; use matched(ref, "regex") meanwhile (hit 2026-09-12 while sealing the sprint-2 map).
  • INPUT values are single-line (#37 in flight) — long single lines are fine, pretty- printed JSON is not (hit 2026-09-12).
  • Worker model endpoints cap concurrency — the internal GLM-5.2 endpoint allows 3 inflight requests; 7 parallel workers → Too Many Requests: inflight limit exceeded (verified 2026-09-12, killed a worker).
  • Launching background workers from a tool call that then times out kills them — the timeout's process-group kill ignores nohup. Launch calls must return instantly; poll separately (verified 2026-09-12, killed five workers).
  • Merging an uncommitted branch is a silent EMPTY merge — workers never commit (contract); the orchestrator must commit each worktree's branch scope BEFORE git merge (bit once 2026-09-12; the suite count exposed it).

Digest versions

Default seals are v1 canonical form. Issue #32 (in flight) adds a v2 digest that canonicalizes IF-conditions and barrier spelling — historical v1 seals must keep verifying; treat any claim about v2 as UNKNOWN until it lands and the seal sweep goes green again.

Files