Harness and CLI¶
tether.harness¶
Control Plane: Tether Harness, bounded agent loop, live SQLite inbox, and headless spawner.
PipelineResumeError
¶
Bases: ValueError
A pipeline session cannot be resumed; the CLI reports it as a usage error.
Harness
¶
General-purpose LLM-Native Micro-Harness.
output_schema (JSON Schema subset) is a deterministic pre-done gate: the deliverable
must be JSON matching it. tether.api.failure_info classifies FAILED results by the
prefixes "Verification gate", "Stopped" and "Worker error".
register(fn_or_spec)
¶
Register a custom Python function or ToolSpec with this Harness.
build_multiplexer(session_id, enabled_tools, sandbox, model, on_approval=None)
¶
Construct the session Multiplexer with done + strictly opted-in tools.
create_pipeline_session(pipeline, goal, *, parent_id=None)
¶
Create a persisted root pipeline session row in SQLite without executing it yet.
spawn_pipeline(pipeline, goal, *, parent_id=None)
¶
Create a pipeline session and launch it as a detached headless worker.
run_pipeline(pipeline, goal, *, parent_id=None)
async
¶
Execute a deterministic multi-stage pipeline with isolated stage sessions.
resume_pipeline(session_id)
async
¶
Re-run a failed or waiting pipeline from its first stage that is not COMPLETED.
create_session(goal, *, parent_id=None)
¶
Create a persisted session row in SQLite without executing it yet.
from_session(rec, *, db_path=None, model=None, max_steps=None, worktree=False, worktree_from=None, setup=None)
classmethod
¶
Rebuild a harness from a stored session (used by tether replay).
Runs in the current directory (the stored workspace_root is not reused). Verify gates are not stored, so they are not restored. With worktree=True the replay runs in its own git worktree (worktree_from sets the base ref). setup is a shell command run in that worktree before the model starts.
spawn(goal, *, parent_id=None)
¶
Create a session and launch it as a detached headless worker, returning session_id.
run(goal, *, parent_id=None)
async
¶
Create and run a session inline until completion (done) or max_steps.
send(session_id, message, *, headless=False)
async
¶
Send a message to SQLite inbox; auto-resumes if WAITING_INPUT/COMPLETED/FAILED.
execute_session(session_id)
async
¶
Run a session. Worktree sessions are committed whenever they stop.
detect_cycle(history, window=8)
¶
Repeated n-gram at the tail of the last window actions, else None.
A 2-gram must repeat 3 times, a 3-gram or 4-gram 2 times, so a legitimate
test / view / test / view pair is not flagged. Identical-command runs are
loop_stall's job, so they are not a cycle here.
read_target(cmd)
¶
File a read-only command inspects (edit view p, sed -n 1,9p p, cat p), else None.
tests_green(cmd, out)
¶
True when cmd is a test runner whose output reports success (#177).
failing_test_source(out, root)
¶
Source of the failing test functions named in a traceback, inside root (#173).
run_outcome(out)
¶
Tests run and failing test names from a unittest or pytest summary, else None (#173).
failing_count(out, names)
¶
Failing tests by the summary line (FAILED (failures=1, errors=2), 3 failed), so a run cut
by head that names only a few still counts them all; at least len(names).
regression_note(before, after)
¶
Note naming the tests the last change broke, when both runs are comparable (#173).
suite_for(rel, root, since)
¶
The test file next to rel (x_test.py or test_x.py) when rel existed at since.
suite_read(cmd, root, since)
¶
(starting file, its test file) when cmd names the test file of a starting file.
is_quiet(cmd)
¶
True if every statement of cmd is read-only or a verification (for f in x; do cat).
tether.cli¶
tether.pipeline¶
Declarative multi-stage deterministic pipelines and heterogeneous model routing.
PipelineStage
dataclass
¶
A single deterministic stage inside a multi-stage Tether pipeline.
Pipeline
dataclass
¶
Declarative multi-stage workflow with isolated sessions and bounded FTS5 handoffs.
parse_pipeline_yaml(raw_yaml, default_name='pipeline')
¶
Parse a YAML string into a validated Pipeline specification.
load_pipeline(path)
¶
Load a declarative YAML pipeline manifest from disk.
render_stage_goal(stage, root_goal, upstream_stages, store)
¶
Render stage goal with {{goal}} interpolation and compact ~50-token upstream digests.