tether-sdk 0.2.8__tar.gz → 0.2.9__tar.gz

{tether_sdk-0.2.8 → tether_sdk-0.2.9}/.claude/gru/active/v0-2-bugs.md

@@ -106,3 +106,5 @@ Track and fix bugs found in Tether v0.2.x. Exact bug list not yet given by PO.
 - 2026-10-25 PO: docs plan. Audit -> epic #150 (steps: CLI ref #61, providers #60+#62, site structure #151, story guides #152, troubleshooting #153, benchmarks #154, README #63, llms.txt #64, polish #65/#66), all in milestone v0.2.10 (v0.2.11 closed, empty). AGENTS.md 5.6 now states the two audiences (docs site = users/integrators, no bug history; README = evaluate/build/contribute). #145 fix on branch fix/79-stats-offenders awaiting fast-set bench then PR.
 - 2026-10-25 Tether friction (docs cards on Nemotron Ultra): (1) ses_f6f847e5 CLI page and ses_7fb5863b providers page both ended at max steps WITHOUT calling done after the work was finished (keeps verifying); (2) rewriting a docs page it invented API facts (wrong ModelResponse fields, register_provider signature, nonexistent settings) -> docs rewrites by tether need a gru fact-check or assemble-from-source approach; (3) 5 steps in 10 min on a 156-line page (slow generation of long outputs on the free endpoint). Merged: #155 policy, #156 CLI ref (#61). PR for #60/#62 open. #145 PR waits for fast-set bench.
 - 2026-10-25 PO: milestones reshuffled: v0.2.8 = release now (#144 #145 + sandbox venv + CLI/providers docs), v0.2.9 = docs overhaul (#150-#154, #63-#66), v0.2.10 = #27 #79 #132-#137. Merged: #146 #148 #149 #155 #156 #157 #158. Release PR v0.2.8 (version bump, notes) prepared; GitHub Release only on PO yes.
+- 2026-10-25 RELEASED v0.2.8 'Room to Answer' (release PR #159 -> f4370b1, GitHub Release, delivery.yml success, PyPI tether-sdk 0.2.8 live, milestone closed). Docs v0.2.9 started: #151 site structure PR (nav = Start here/Guides/Concepts/Reference/Help, 'For:' line per page, CONTRIBUTING.md replaces docs/testing.md + releasing.md, tests/test_docs_structure.py). Lesson: ruff format --check also formats Python blocks in docs; renamed anchors break the strict mkdocs build via old release-notes links -> run both before pushing docs.
+- 2026-10-25 PO: 'merge all docs PRs and cut the next version'. Docs plan (#150) done: #155 #156 #157 #160 #161 #162 #165 #166 #167 merged, epic closed. Found #163 while writing guide 1 (qwen3.5:9b fixes the test, passes, never calls done -> FAILED Stalled); #164 merged on PO yes (Rule 3 reading: passing verify gates at stall time -> COMPLETED). Release PR v0.2.9 prepared. Next: v0.2.10 = #27 #79 #132-#137 (8 issues; pick by evidence, e.g. bench failure breakdown after v0.2.9). Tether friction this stretch: docs rewrites by Nemotron invent API facts and end without done; harness.py cards need 40+ steps.

{tether_sdk-0.2.8 → tether_sdk-0.2.9}/AGENTS.md

@@ -46,7 +46,7 @@ Reviewers and the Team Leader cite the failing line when they reject a change.
 - A task only completes when the agent explicitly calls `act("done", stdin="<final deliverable>")` (or `act("done '<short answer>'")`), pauses for human/parent input via `act("done --ask", stdin="<question>")` (transitioning the session to `WAITING_INPUT` and releasing the worker process until resumed via `send`), or hits `max_steps`.
 - If the model emits plain text without calling `act`, the harness appends a brief deterministic nudge reminding it to either execute a command or call `done`.
 - After 6 consecutive read-only/verification steps following a change, the harness appends a one-shot `[NUDGE]` to that step's observation reminding the model to call `done` if the task is complete (0 static prompt tokens, #74). Before any change, 12 read-only steps in a row (then every 8 more) append a one-line `[NUDGE]` to make the edit or call `done` (#127). Seven reads of one file in a row with no change are a `cycle_stall`, and 4 stall warnings without a change end the session `FAILED` as `Stalled` (#92); `tether stop <id>` terminates a detached worker (#89).
-- When `verify` gate commands are configured (via `Harness(verify=[...])`, CLI `--verify`, or Skill YAML `verify: [...]`), `Harness.execute_session` deterministically executes each command inside the session's `SandboxPolicy` before allowing `done` to transition to `COMPLETED` (consuming 0 static prompt tokens until a gate fails). A gate that errors instead of failing (sandbox violation, exit 124/126/127) ends the session `FAILED` at once as `gate_error` ("gate misconfigured"), without counting toward the consecutive-failure abort.
+- When `verify` gate commands are configured (via `Harness(verify=[...])`, CLI `--verify`, or Skill YAML `verify: [...]`), `Harness.execute_session` deterministically executes each command inside the session's `SandboxPolicy` before allowing `done` to transition to `COMPLETED` (consuming 0 static prompt tokens until a gate fails). A gate that errors instead of failing (sandbox violation, exit 124/126/127) ends the session `FAILED` at once as `gate_error` ("gate misconfigured"), without counting toward the consecutive-failure abort. When the stall guard is about to end a session as `Stalled` and gates are configured, it runs them first: a change was made and every gate passes, so the session ends `COMPLETED` ("Finished by the harness"), since the deterministic gate is the completion criterion the caller asked for (#163).
 
 ### Rule 4: Progressive `--help` (JIT Schema Disclosure)
 - The system prompt lists at most **1 line per enabled tool namespace** (`- <name>: <short summary>`, target **≤ 12 tokens per entry**).
@@ -206,8 +206,8 @@ uv run mypy tether/
    - All model calls and I/O-bound tool executions must be `async`/`await` native, while seamlessly wrapping synchronous user `@tool` functions.
 3. **Graceful Degradation on 9B Hallucinations:**
    - Small models occasionally emit `cmd` with minor quirks (e.g., leading `$`, wrapping backticks, or calling a tool name directly instead of `act`). The multiplexer must normalize trivial syntax quirks deterministically before failing. This includes unescaping literal `\n`/`\t` in one-line `stdin` for `edit write`/`edit replace` and `done` (never `bash`), turning a trailing shell heredoc in `cmd` (`edit write f <<'EOF' ... EOF`) into `stdin` (never for `bash`), unwrapping `bash -c/-lc '<cmd>'` and `sh -c` wrappers, running an unknown first word through the enabled `bash` tool (never for disabled built-ins), registering extra quirk fixers with `register_normalizer`, mapping a native tool call named other than `act` to `<name> --k 'v'` so the JIT usage answers it, inferring the `edit` verb (`edit <path>` -> view/replace/write) and accepting `apply_patch` (`*** Begin Patch` or unified-diff patches, also when a diff arrives as `edit <path>` stdin) as an `edit` verb.
-4. **Golden traces:** behaviour the model sees (framing, folding, nudges, tool output) is locked by `tests/golden/*.snap.json`. A PR that changes it runs `UPDATE_GOLDEN=1 pytest tests/test_golden.py` and the snapshot diff is part of the review; unrelated traces must not change. See `docs/testing.md`.
-5. **E2E scenarios:** every feature or bug fix ships with a scenario in `e2e/` (real CLI, real ollama behind a fault-injecting proxy, local only, `TETHER_E2E=1 uv run pytest e2e`). Assert on what tether sends and records, never on the model's skill; script the reply or inject the fault so the test does not depend on model potency. **Before merging any PR, run `TETHER_E2E=1 uv run pytest e2e` locally and put the result in the PR description (CI cannot run it). Every failure must be mitigated before merge: fix the code, or fix a wrong scenario, or record in the PR why it is acceptable and what follows up. A PR is not merged with an unexplained red scenario.** See `docs/testing.md`.
+4. **Golden traces:** behaviour the model sees (framing, folding, nudges, tool output) is locked by `tests/golden/*.snap.json`. A PR that changes it runs `UPDATE_GOLDEN=1 pytest tests/test_golden.py` and the snapshot diff is part of the review; unrelated traces must not change. See `CONTRIBUTING.md`.
+5. **E2E scenarios:** every feature or bug fix ships with a scenario in `e2e/` (real CLI, real ollama behind a fault-injecting proxy, local only, `TETHER_E2E=1 uv run pytest e2e`). Assert on what tether sends and records, never on the model's skill; script the reply or inject the fault so the test does not depend on model potency. **Before merging any PR, run `TETHER_E2E=1 uv run pytest e2e` locally and put the result in the PR description (CI cannot run it). Every failure must be mitigated before merge: fix the code, or fix a wrong scenario, or record in the PR why it is acceptable and what follows up. A PR is not merged with an unexplained red scenario.** See `CONTRIBUTING.md`.
 6. **Documentation Integrity:**
    - Keep `README.md` and `AGENTS.md` synchronized whenever architectural interfaces or built-in tool signatures change.
    - **Always update documentation in the same PR** when introducing a new feature, changing an existing behavior, or altering a CLI/SDK interface. This covers `README.md`, `AGENTS.md`, the MkDocs pages under `docs/` (including `docs/reference/*` for new modules), and a `docs/release-notes.md` entry. A change without matching docs is incomplete.

tether_sdk-0.2.8/docs/testing.md → tether_sdk-0.2.9/CONTRIBUTING.md

@@ -1,4 +1,24 @@
-# Testing: golden traces
+# Contributing to tether
+
+Thanks for helping. Tether stays **lightweight, reliable, extensible, model-agnostic, easy to use, resourceful and a token saver**: that list (the *Philosophy Gate*) and the architectural rules live in [AGENTS.md](AGENTS.md), which is the authoritative guide for contributors and coding agents. Read its sections 1-3 before changing behaviour.
+
+## Setup and checks
+
+```bash
+uv sync                                                        # environment
+uv run ruff check . && uv run ruff format --check .            # lint and format (also formats Python in docs)
+uv run mypy tether/                                            # types
+uv run pytest --cov=tether --cov-report=term-missing --cov-fail-under=100   # unit tests, 100% coverage (CI)
+TETHER_E2E=1 uv run pytest e2e                                 # e2e, local only (needs the tether-ollama container)
+```
+
+## Pull requests
+
+- One PR per task, Conventional Commits (`feat(scope): ... (#N)`, `fix(...)`, `docs(...)`, `release: vX.Y.Z ...`), squash-merged to `main`.
+- Update the docs in the same PR (README, the MkDocs pages, `docs/release-notes.md`); see *Two audiences, two jobs* in AGENTS.md section 5.6 for what belongs where.
+- A behaviour change carries a measured result in the PR body (bench or e2e delta), reported honestly even when it is flat. Put the `TETHER_E2E=1 uv run pytest e2e` result in the PR; CI cannot run it.
+
+## Testing: golden traces, e2e scenarios and the model bench
 
 Tether is a deterministic envelope around a random model, so a change to framing, folding,
 nudges, tools or retries can silently change what the model is shown. Golden traces make that
@@ -20,7 +40,7 @@ Shipped traces: a real researcher run (web stubbed, plain-text `done` nudges), a
 coding run covering the edit failure modes seen with small models, and a `done --ask` /
 `send` resume, and a range ping-pong (alternating views of one file; the latest read of each range stays unfolded, older ones fold). Add one for every behaviour that must not regress.
 
-## End-to-end scenarios (local, real processes, real ollama)
+### End-to-end scenarios (local, real processes, real ollama)
 
 `e2e/` drives the real `tether` CLI in a throwaway workspace. A small fault-injecting proxy
 (`e2e/proxy.py`) sits between tether and ollama, so a scenario can force the situation instead of
@@ -83,7 +103,7 @@ judge (answer quality).
 **Rule:** a new feature or bug fix ships with a scenario here. If a model must misbehave to
 trigger it, script the reply; if infrastructure must fail, add a fault to the proxy.
 
-## Model conformance bench (developers only)
+### Model conformance bench (developers only)
 
 `bench/` holds nine tasks (the `focus` task checks that an exact single-file goal is not lost in a distractor-heavy repo) with hidden-test graders and three runners (Tether, a plain tool loop,
 Claude Code) so the same model can be compared across harnesses and releases. It needs real
@@ -91,3 +111,14 @@ models, so it is not in CI and not in the package: use it when onboarding a mode
 release to see friction that scripted tests cannot (the shell-wrapper, bare-command and
 tool-name failures behind #109 were found this way). Anything it finds that can be scripted
 becomes a unit, golden or e2e test. See `bench/README.md`.
+
+## Releasing
+
+PyPI is published only from a GitHub Release, never from a push or tag.
+
+0. Re-run the commands in `docs/guides/` against the release candidate and fix any output that changed.
+1. Bump `__version__` in `tether/__init__.py` (and the version assertion in `tests/test_tether.py`) and update `docs/release-notes.md`.
+2. Merge to `main`.
+3. Create a GitHub Release with tag `v<version>` (for example `v0.1.0`). The tag must match `__version__` (a leading `v` is ignored) or the workflow fails before building.
+
+The `delivery.yml` workflow then verifies the tag, builds the sdist and wheel, publishes to PyPI with trusted publishing (no secrets) and attaches both files to the release. Pre-releases are skipped: nothing is published or attached.

tether_sdk-0.2.9/PKG-INFO

@@ -0,0 +1,143 @@
+Metadata-Version: 2.5
+Name: tether-sdk
+Version: 0.2.9
+Summary: General-purpose, headless-first LLM-Native micro-harness for small language models
+Project-URL: Homepage, https://github.com/igormcsouza/tether
+Project-URL: Repository, https://github.com/igormcsouza/tether
+Project-URL: Documentation, https://igormcsouza.github.io/tether/
+Author-email: Igor Souza <igormcsouza@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agents,cli,harness,llm,slm,sqlite
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.12
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: pyyaml>=6.0.1
+Provides-Extra: mcp
+Requires-Dist: mcp<3,>=2.0; extra == 'mcp'
+Description-Content-Type: text/markdown
+
+# 🪢 Tether
+
+**A small, headless-first harness that lets small local models (and frontier ones) do real work with a tiny prompt.**
+
+[![PyPI](https://img.shields.io/pypi/v/tether-sdk?color=0d9488&label=PyPI%20%7C%20tether-sdk)](https://pypi.org/project/tether-sdk/)
+[![Docs](https://img.shields.io/badge/Docs-igormcsouza.github.io%2Ftether-0d9488)](https://igormcsouza.github.io/tether/)
+[![Python](https://img.shields.io/badge/Python-3.12%2B-3b82f6)](#install-and-first-run)
+[![Models](https://img.shields.io/badge/Models-Ollama%20%7C%20OpenAI--compatible%20%7C%20Claude-10b981)](https://igormcsouza.github.io/tether/reference/providers/)
+
+```bash
+uv tool install tether-sdk
+tether run --model ollama/qwen3.5:9b --tools bash,edit --verify "pytest -q" "fix the failing tests"
+```
+
+## Why Tether
+
+Most agent frameworks treat the context window as a dumping ground. Before your task is read, they inject **3,000 to 8,000 tokens** of JSON tool schemas and system prompt, then append every tool output forever. On a frontier model that is money. On a 9B model running on your laptop it is fatal: attention is diluted, small models fumble nested JSON, and changing the tool list between turns throws away the inference server's KV cache.
+
+Tether is built the other way round:
+
+- **One tool, not thirty.** The model sees a single `act(cmd, stdin)` schema. Everything else (`bash`, `edit`, `web`, `mem`, your own functions) is a command behind it, off by default. Fixed framing is under 150 tokens.
+- **Old output folds away.** Tool results stay in full for two turns, then become a one-line tombstone. Everything lives in SQLite and comes back by search.
+- **The envelope is deterministic.** Sandboxing, state, step limits, verification gates and termination are plain code. The model only reasons; it is never trusted with safety.
+
+## How well does it work
+
+Tether answers to one number: how many real coding exercises a small local model finishes. On the Polyglot-Python set (Aider's 34 Python exercises, graded by each exercise's own tests), `qwen3.5:9b` through Ollama, 12-exercise fast set, 2 trials each:
+
+| | v0.2.7 | v0.2.8 |
+|---|---|---|
+| Passes | 10 of 24 | 11 of 24 |
+| Mean score | 0.741 | 0.756 |
+| "Tool call cut off" hints | 29 | 2 |
+| Steps that did nothing | 19% | 2.2% |
+
+One run is noisy (about 0.1), so read the pass count and the failure breakdown, not one decimal. Method, how to reproduce it and fair-comparison rules: [Benchmarks](https://igormcsouza.github.io/tether/benchmarks/). Every change that touches model-visible behaviour has to move this number or leave it alone.
+
+## How it works
+
+```mermaid
+flowchart LR
+    You["CLI · SDK · MCP"] --> Loop
+    subgraph Envelope["Deterministic envelope"]
+        Loop["bounded loop<br/>steps · stall guard · gates"] --> Mux["act(cmd, stdin)<br/>command bus"]
+        Mux --> Sand["sandbox<br/>bwrap · workspace jail"]
+        Sand --> Tools["bash · edit · web · mem · agent · your @tool"]
+        Tools --> Fold["fold old output"]
+        Fold --> DB[("SQLite WAL + FTS5<br/>.tether/tether.db")]
+        DB --> Loop
+    end
+    Loop <-->|"messages"| Model["LLM<br/>ollama · openai · anthropic"]
+```
+
+A session is a row in SQLite, so it survives crashes, runs detached (`--headless`), takes new instructions while running (`tether send`), and can be read by another agent as compact JSON. A task ends only when the model calls `done`, after your `--verify` commands pass.
+
+## Why this and not that
+
+| Decision | Instead of | Why |
+|---|---|---|
+| One `act` tool, commands behind it | A JSON schema per tool | CodeAct and SWE-agent results: one executable channel beats many schemas, most for 7-9B models; and the prompt prefix never changes, so the KV cache survives. |
+| Progressive `--help` | Full usage up front | A tool costs about a dozen tokens until the model asks or gets it wrong. |
+| SQLite (WAL, FTS5) as memory | An ever-growing transcript | Context stays a bounded working set; the rest is searchable. State is ACID, so sessions resume and agents share results. |
+| Kernel sandbox (`bwrap`), env scrubbing, SSRF guard | "Please be careful" in the prompt | Safety that depends on the model obeying is not safety. |
+| Explicit `done` plus verification gates | Letting the model declare success | Small models stop early or never stop. The gate is a command you wrote. |
+| Thin `httpx` adapters, 2 runtime dependencies | Vendor SDKs, LangChain-style frameworks | Easy to read, easy to add a backend (`providers.yaml`, no code), nothing to upgrade around. |
+
+The research behind it: Maia et al. (2026) on probabilistic core and deterministic envelope, Wang et al. (2024, CodeAct), Yang et al. (2024, SWE-agent) and Packer et al. (2023, MemGPT); see [References](#references) and [Architecture](https://igormcsouza.github.io/tether/architecture/).
+
+## Install and first run
+
+```bash
+uv tool install tether-sdk            # or: pip install tether-sdk
+ollama pull qwen3.5:9b                # any model works; see the providers page
+tether run --model ollama/qwen3.5:9b --tools bash,edit "create hello.txt containing hi"
+```
+
+Everything else (headless sessions, skills, pipelines, MCP, the CLI reference, writing your own tool or provider) is in the docs: **[igormcsouza.github.io/tether](https://igormcsouza.github.io/tether/)**. Start with the guides: [fix a failing test](https://igormcsouza.github.io/tether/guides/fix-a-failing-test/), [use it from Claude Code or Codex](https://igormcsouza.github.io/tether/guides/use-tether-from-your-agent/).
+
+## Build on it
+
+```python
+import asyncio
+
+from tether import Harness, tool
+
+
+@tool(name="price", description="Look up the unit price of a fruit")
+def price(fruit: str) -> str:
+    return f"{fruit}: 0.50 EUR"
+
+
+async def main() -> None:
+    harness = Harness(model="ollama/qwen3.5:9b", tools=[price])
+    session = await harness.run("What does an apple cost?")
+    print(session.result)
+
+
+asyncio.run(main())
+```
+
+`Harness`, `Pipeline`, `Skill`, `SandboxPolicy`, `@tool` and `register_provider` are the public surface. The agent-facing JSON and the optional `tether mcp` server (`tether-sdk[mcp]`) are specified in the [reference](https://igormcsouza.github.io/tether/reference/agent-interface/).
+
+## Contributing
+
+Tether stays lightweight, reliable, extensible, model-agnostic, easy to use, resourceful and a token saver; a change that fails one of those lines is reworked. Read [AGENTS.md](AGENTS.md) (the rules and the module map) and [CONTRIBUTING.md](CONTRIBUTING.md) (setup, checks, golden traces, e2e, the bench, releasing). Open an issue before a large change; small fixes with a test and a docs line are welcome as they are.
+
+```text
+tether/        harness · multiplexer · context · store · sandbox · providers/ · tools/
+tests/         unit, golden traces (what the model sees), 100% coverage
+e2e/           real CLI and real Ollama behind a fault-injecting proxy (local)
+bench/         Polyglot-Python and model checks (developers)
+docs/          the user site (MkDocs)
+```
+
+---
+
+## References
+
+1. **Maia, P. H. M., et al. (2026).** *LLM-Native Applications as a Paradigm for AI-Driven Software Architecture*.
+2. **Wang, X., Chen, Y., Yuan, L., Zhang, Y., Li, Y., Peng, H., & Ji, H. (2024).** *Executable Code Actions Elicit Better LLM Agents (CodeAct)*. In **Proceedings of the 41st International Conference on Machine Learning (ICML 2024)**. [arXiv:2402.01030](https://arxiv.org/abs/2402.01030)
+3. **Yang, J., Jimenez, C. E., Wettig, A., Lieret, K., Yao, S., Narasimhan, K., & Press, O. (2024).** *SWE-agent: Agent-Computer Interfaces Enable Automated Software Engineering*. In **Advances in Neural Information Processing Systems (NeurIPS 2024)**. [arXiv:2405.15793](https://arxiv.org/abs/2405.15793)
+4. **Packer, C., Wooders, S., Lin, K., Fang, V., Patil, S. G., Stoica, I., & Gonzalez, J. E. (2023).** *MemGPT: Towards LLMs as Operating Systems*. [arXiv:2310.08560](https://arxiv.org/abs/2310.08560)

tether_sdk-0.2.9/README.md

@@ -0,0 +1,122 @@
+# 🪢 Tether
+
+**A small, headless-first harness that lets small local models (and frontier ones) do real work with a tiny prompt.**
+
+[![PyPI](https://img.shields.io/pypi/v/tether-sdk?color=0d9488&label=PyPI%20%7C%20tether-sdk)](https://pypi.org/project/tether-sdk/)
+[![Docs](https://img.shields.io/badge/Docs-igormcsouza.github.io%2Ftether-0d9488)](https://igormcsouza.github.io/tether/)
+[![Python](https://img.shields.io/badge/Python-3.12%2B-3b82f6)](#install-and-first-run)
+[![Models](https://img.shields.io/badge/Models-Ollama%20%7C%20OpenAI--compatible%20%7C%20Claude-10b981)](https://igormcsouza.github.io/tether/reference/providers/)
+
+```bash
+uv tool install tether-sdk
+tether run --model ollama/qwen3.5:9b --tools bash,edit --verify "pytest -q" "fix the failing tests"
+```
+
+## Why Tether
+
+Most agent frameworks treat the context window as a dumping ground. Before your task is read, they inject **3,000 to 8,000 tokens** of JSON tool schemas and system prompt, then append every tool output forever. On a frontier model that is money. On a 9B model running on your laptop it is fatal: attention is diluted, small models fumble nested JSON, and changing the tool list between turns throws away the inference server's KV cache.
+
+Tether is built the other way round:
+
+- **One tool, not thirty.** The model sees a single `act(cmd, stdin)` schema. Everything else (`bash`, `edit`, `web`, `mem`, your own functions) is a command behind it, off by default. Fixed framing is under 150 tokens.
+- **Old output folds away.** Tool results stay in full for two turns, then become a one-line tombstone. Everything lives in SQLite and comes back by search.
+- **The envelope is deterministic.** Sandboxing, state, step limits, verification gates and termination are plain code. The model only reasons; it is never trusted with safety.
+
+## How well does it work
+
+Tether answers to one number: how many real coding exercises a small local model finishes. On the Polyglot-Python set (Aider's 34 Python exercises, graded by each exercise's own tests), `qwen3.5:9b` through Ollama, 12-exercise fast set, 2 trials each:
+
+| | v0.2.7 | v0.2.8 |
+|---|---|---|
+| Passes | 10 of 24 | 11 of 24 |
+| Mean score | 0.741 | 0.756 |
+| "Tool call cut off" hints | 29 | 2 |
+| Steps that did nothing | 19% | 2.2% |
+
+One run is noisy (about 0.1), so read the pass count and the failure breakdown, not one decimal. Method, how to reproduce it and fair-comparison rules: [Benchmarks](https://igormcsouza.github.io/tether/benchmarks/). Every change that touches model-visible behaviour has to move this number or leave it alone.
+
+## How it works
+
+```mermaid
+flowchart LR
+    You["CLI · SDK · MCP"] --> Loop
+    subgraph Envelope["Deterministic envelope"]
+        Loop["bounded loop<br/>steps · stall guard · gates"] --> Mux["act(cmd, stdin)<br/>command bus"]
+        Mux --> Sand["sandbox<br/>bwrap · workspace jail"]
+        Sand --> Tools["bash · edit · web · mem · agent · your @tool"]
+        Tools --> Fold["fold old output"]
+        Fold --> DB[("SQLite WAL + FTS5<br/>.tether/tether.db")]
+        DB --> Loop
+    end
+    Loop <-->|"messages"| Model["LLM<br/>ollama · openai · anthropic"]
+```
+
+A session is a row in SQLite, so it survives crashes, runs detached (`--headless`), takes new instructions while running (`tether send`), and can be read by another agent as compact JSON. A task ends only when the model calls `done`, after your `--verify` commands pass.
+
+## Why this and not that
+
+| Decision | Instead of | Why |
+|---|---|---|
+| One `act` tool, commands behind it | A JSON schema per tool | CodeAct and SWE-agent results: one executable channel beats many schemas, most for 7-9B models; and the prompt prefix never changes, so the KV cache survives. |
+| Progressive `--help` | Full usage up front | A tool costs about a dozen tokens until the model asks or gets it wrong. |
+| SQLite (WAL, FTS5) as memory | An ever-growing transcript | Context stays a bounded working set; the rest is searchable. State is ACID, so sessions resume and agents share results. |
+| Kernel sandbox (`bwrap`), env scrubbing, SSRF guard | "Please be careful" in the prompt | Safety that depends on the model obeying is not safety. |
+| Explicit `done` plus verification gates | Letting the model declare success | Small models stop early or never stop. The gate is a command you wrote. |
+| Thin `httpx` adapters, 2 runtime dependencies | Vendor SDKs, LangChain-style frameworks | Easy to read, easy to add a backend (`providers.yaml`, no code), nothing to upgrade around. |
+
+The research behind it: Maia et al. (2026) on probabilistic core and deterministic envelope, Wang et al. (2024, CodeAct), Yang et al. (2024, SWE-agent) and Packer et al. (2023, MemGPT); see [References](#references) and [Architecture](https://igormcsouza.github.io/tether/architecture/).
+
+## Install and first run
+
+```bash
+uv tool install tether-sdk            # or: pip install tether-sdk
+ollama pull qwen3.5:9b                # any model works; see the providers page
+tether run --model ollama/qwen3.5:9b --tools bash,edit "create hello.txt containing hi"
+```
+
+Everything else (headless sessions, skills, pipelines, MCP, the CLI reference, writing your own tool or provider) is in the docs: **[igormcsouza.github.io/tether](https://igormcsouza.github.io/tether/)**. Start with the guides: [fix a failing test](https://igormcsouza.github.io/tether/guides/fix-a-failing-test/), [use it from Claude Code or Codex](https://igormcsouza.github.io/tether/guides/use-tether-from-your-agent/).
+
+## Build on it
+
+```python
+import asyncio
+
+from tether import Harness, tool
+
+
+@tool(name="price", description="Look up the unit price of a fruit")
+def price(fruit: str) -> str:
+    return f"{fruit}: 0.50 EUR"
+
+
+async def main() -> None:
+    harness = Harness(model="ollama/qwen3.5:9b", tools=[price])
+    session = await harness.run("What does an apple cost?")
+    print(session.result)
+
+
+asyncio.run(main())
+```
+
+`Harness`, `Pipeline`, `Skill`, `SandboxPolicy`, `@tool` and `register_provider` are the public surface. The agent-facing JSON and the optional `tether mcp` server (`tether-sdk[mcp]`) are specified in the [reference](https://igormcsouza.github.io/tether/reference/agent-interface/).
+
+## Contributing
+
+Tether stays lightweight, reliable, extensible, model-agnostic, easy to use, resourceful and a token saver; a change that fails one of those lines is reworked. Read [AGENTS.md](AGENTS.md) (the rules and the module map) and [CONTRIBUTING.md](CONTRIBUTING.md) (setup, checks, golden traces, e2e, the bench, releasing). Open an issue before a large change; small fixes with a test and a docs line are welcome as they are.
+
+```text
+tether/        harness · multiplexer · context · store · sandbox · providers/ · tools/
+tests/         unit, golden traces (what the model sees), 100% coverage
+e2e/           real CLI and real Ollama behind a fault-injecting proxy (local)
+bench/         Polyglot-Python and model checks (developers)
+docs/          the user site (MkDocs)
+```
+
+---
+
+## References
+
+1. **Maia, P. H. M., et al. (2026).** *LLM-Native Applications as a Paradigm for AI-Driven Software Architecture*.
+2. **Wang, X., Chen, Y., Yuan, L., Zhang, Y., Li, Y., Peng, H., & Ji, H. (2024).** *Executable Code Actions Elicit Better LLM Agents (CodeAct)*. In **Proceedings of the 41st International Conference on Machine Learning (ICML 2024)**. [arXiv:2402.01030](https://arxiv.org/abs/2402.01030)
+3. **Yang, J., Jimenez, C. E., Wettig, A., Lieret, K., Yao, S., Narasimhan, K., & Press, O. (2024).** *SWE-agent: Agent-Computer Interfaces Enable Automated Software Engineering*. In **Advances in Neural Information Processing Systems (NeurIPS 2024)**. [arXiv:2405.15793](https://arxiv.org/abs/2405.15793)
+4. **Packer, C., Wooders, S., Lin, K., Fang, V., Patil, S. G., Stoica, I., & Gonzalez, J. E. (2023).** *MemGPT: Towards LLMs as Operating Systems*. [arXiv:2310.08560](https://arxiv.org/abs/2310.08560)

{tether_sdk-0.2.8 → tether_sdk-0.2.9}/bench/README.md

@@ -2,7 +2,7 @@
 
 Not part of the `tether` package, not run in CI. Use it to onboard a new model or to check a
 release for regressions that deterministic tests cannot see (unit, golden and e2e tests stay the
-gate; see `docs/testing.md`).
+gate; see `CONTRIBUTING.md`).
 
 Nine tasks in `tasks/<name>/` (workspace in `ws/`, goal in `goal.txt`, hidden tests in `hidden/`):
 `focus` (one exact edit in a distractor-heavy repo, scope-checked), `plan` (an implementation plan, checked for named files, failure handling and tests), `codereview` (eight seeded bugs to find, no edits), `code-simple`, `code-medium`, `code-hard` (graded by hidden unit tests; editing the visible tests

{tether_sdk-0.2.8 → tether_sdk-0.2.9}/docs/architecture.md

@@ -1,5 +1,7 @@
 # Architecture and Literature
 
+*For: people who want to understand why tether works the way it does, and what each design choice costs or saves.*
+
 Most agent frameworks were designed around massive frontier models with 200k-token context windows. When you point those same frameworks at a local 8B or 9B model (`ollama/qwen3.5:9b`, `ollama/gemma4:e4b`), they immediately fail—not because the model cannot reason, but because **3,000 to 8,000 tokens of nested JSON tool schemas and raw tool outputs** flood the attention window before the agent takes its second step.
 
 Tether's design translates four foundational works in recent AI systems research into a compact, zero-bloat Python micro-harness.

tether_sdk-0.2.9/docs/benchmarks.md

@@ -0,0 +1,50 @@
+# Benchmark Evaluation
+
+*For: people comparing tether with other harnesses, and anyone checking that a release did not make small models worse. It shows what is measured, how, and the latest numbers.*
+
+Tether is judged on one score: **how many real coding exercises a small local model finishes** when tether is the harness around it. That is the number every change has to improve, or at least not lower.
+
+## What is measured
+
+The **Polyglot-Python** set: the 34 Python exercises of Aider's [polyglot benchmark](https://github.com/Aider-AI/polyglot-benchmark) (poker hands, a Forth interpreter, a REST API, a reactive spreadsheet, ...). For each exercise the model gets a workspace with a stub and the exercise's own test file, and a goal: make the tests pass.
+
+- **Graded by the exercise's own tests.** The test file is restored before grading, so editing it cannot pass.
+- **Score** is the fraction of tests that pass (so a partial solution counts); a *pass* is every test green.
+- The **fast set** is 12 exercises that mix passes, partial results and failures, run twice each (24 runs): about an hour and a half on one local GPU, enough to see a change without waiting for the full 34.
+
+## Latest result
+
+`qwen3.5:9b` through Ollama (`num_ctx` 8192), fast set, 2 trials per exercise:
+
+| | v0.2.7 | v0.2.8 |
+|---|---|---|
+| Passes | 10 of 24 | 11 of 24 |
+| Mean score | 0.741 | 0.756 |
+| Mean score, runs without a provider outage | 0.772 | 0.775 |
+| "Tool call cut off" hints (runs that had one) | 29 (9) | 2 (1) |
+| Steps that did nothing (no tool call) | 19% | 2.2% |
+
+What changed between them: tether now keeps a quarter of the context window free for the model's reply. Before, a prompt that filled the window cut off the longest tool calls (file writes), and every cut cost a step. Pass counts and scores moved little; the waste almost disappeared.
+
+**Read these numbers with care.** One run of one exercise is noisy (about 0.1 of score), 24 runs are a small sample, and a local server can time out for reasons that have nothing to do with tether. A difference smaller than that noise is not a result. The *failure breakdown* in the report keeps provider outages and timeouts apart from harness outcomes (`max_steps`, `stalled`, `wrong_answer`, `worker_error`) so you can see which one moved.
+
+## Run it yourself
+
+The benchmark lives in `bench/` of the repository (not in the package, not in CI). It needs the exercises cloned once and a model to run:
+
+```bash
+# fast set, two trials, one local model
+uv run python bench/run.py --runners tether --models ollama/qwen3.5:9b \
+    --tasks polyglot-fast --trials 2 --out /tmp/bench
+
+# pass rate, mean score and the failure breakdown
+python3 bench/report.py /tmp/bench
+```
+
+Use `--tasks polyglot` for all 34 exercises, `--tether-bin /path/to/venv/bin/tether` to compare two versions on the same machine, and `--redo-infra` to rerun cells that failed on a provider outage. To attribute a gap to the harness rather than the model, add `--runners tether,naive`: the `naive` runner is a plain tool loop with the same model and the same exercises. Details and the smaller non-coding tasks: [`bench/README.md`](https://github.com/igormcsouza/tether/blob/main/bench/README.md).
+
+## How to compare fairly
+
+- Same model, same server, same `num_ctx`, same machine; run both versions in the same session (a busy GPU changes timeouts).
+- Report pass count **and** mean score, with the failure breakdown.
+- Do not draw a conclusion from a single trial of a single exercise.

{tether_sdk-0.2.8 → tether_sdk-0.2.9}/docs/extending.md

@@ -1,5 +1,7 @@
 # Extending Tether
 
+*For: developers adding tools or model backends. After this page you can extend tether without touching its core.*
+
 Tether is designed around small, explicit protocols so you can plug in custom model gateways, local inference engines, or domain tool suites without subclassing framework base classes.
 
 ## 1. Custom Model Providers

tether_sdk-0.2.9/docs/glossary.md

@@ -0,0 +1,29 @@
+# Glossary
+
+*For: anyone meeting a tether term for the first time. Each entry is one sentence you can act on.*
+
+**Act.** The single tool the model sees: `act(cmd, stdin)`. Every command (`bash`, `edit`, `done`, your own) goes through it.
+
+**ACI (agent-computer interface).** The command line the model works with. Tether keeps it small and forgiving: compact usage, helpful errors, normalised quirks.
+
+**Dialect.** A reply format a model uses instead of a proper tool call (for example a `<tool_call>` block). Tether parses known dialects into the same action; add your own with a `dialects:` regex.
+
+**Fold / tombstone.** After a few turns, a tool output is replaced in the prompt by a one-line stand-in (the tombstone). The full text stays in SQLite and can be searched or recalled.
+
+**FTS5 RAG.** Retrieval over SQLite's full-text index (BM25 ranking). `mem search` and `agent query` use it to pull only the relevant chunks, with no embedding model.
+
+**Gate (verification gate).** A command you supply with `--verify` that tether runs itself before accepting `done`. A failing gate sends its output back to the model.
+
+**Headless.** A session run detached in the background (`--headless`). You check it with `tether status`, `wait` and `read`, and steer it with `tether send`.
+
+**Nudge.** A one-line reminder tether adds when the model answers in plain text, or keeps reading after a change, so it acts or calls `done`.
+
+**Pipeline.** An ordered set of stages in YAML; each stage is its own session with its own model, tools and gate.
+
+**Session.** One run of the loop, stored as a row in `.tether/tether.db`. It can be resumed, sent messages and read by another agent.
+
+**Skill.** A Markdown file with YAML frontmatter that packages instructions, model, tools and gates for a repeatable job.
+
+**Stall.** The model repeating a command, cycling, or re-reading one file without changing anything. Tether warns, and ends the session early if it continues.
+
+**Workspace.** The directory a session may read and write. Everything outside it is blocked by the sandbox.

tether_sdk-0.2.9/docs/guides/a-pipeline-with-checks.md

@@ -0,0 +1,70 @@
+# Run a pipeline where each stage has its own job
+
+*For: people with a task that has an order: gather, then write, then check. After this page you can run a declarative pipeline, give each stage its own model, tools and gate, and read the results.*
+
+A single long conversation gets confused. A **pipeline** splits the job into stages, each in its own clean session with its own tools and its own check, and passes a compact summary from one stage to the next.
+
+## The job
+
+Turn a list of changes into a short release note. Stage one only reads (and cannot write anything); stage two writes the file and must produce a non-empty `NOTE.md` before it may finish.
+
+`changes.txt`:
+
+```text
+- csv export added to the reports page
+- empty cart no longer crashes checkout
+- install steps rewritten for Windows
+```
+
+`release-note.yaml`:
+
+```yaml
+name: release-note
+stages:
+  - id: facts
+    model: ollama/qwen3.5:9b
+    tools: [bash]
+    sandbox: read-only          # this stage cannot change anything
+    goal: "Read changes.txt and call done with the list of changes, one per line. Task: {{goal}}"
+  - id: write
+    model: ollama/qwen3.5:9b    # could be a different, stronger model
+    tools: [bash, edit]
+    verify: ["test -s NOTE.md"] # the stage cannot finish without this
+    goal: "Using the changes from the previous stage, write NOTE.md: a three-sentence plain-English release note. Then call done."
+```
+
+## Run it
+
+```bash
+tether pipeline release-note.yaml "write the release note"
+```
+
+It finished in 19 seconds. `NOTE.md`:
+
+```text
+This release adds CSV export functionality to the reports page.
+The checkout process now handles empty carts without crashing.
+Install steps have been rewritten for better Windows compatibility.
+```
+
+`tether list` shows the three sessions: the pipeline itself and one per stage, each with its own status and step count.
+
+```text
+ses_61eda63a   COMPLETED  ...   2/2    write the release note      (the pipeline)
+ses_3f575a5b   COMPLETED  ...   4/15   Using the changes from the previous stage, ...
+ses_f6b0921b   COMPLETED  ...   2/15   Read changes.txt and call done with the list ...
+```
+
+## Why this helps
+
+- **Clean context per stage.** The write stage did not see the reading stage's raw output, only a compact digest of its result (about 50 tokens), and it can query the earlier stage on demand.
+- **A model per job.** Put a stronger or paid model only on the stage that needs it.
+- **Narrowing only.** A stage can reduce the sandbox (`read-only`, fewer tools) but never widen what the pipeline allows.
+
+## When it goes wrong
+
+- **A stage ends `Max steps reached`.** Raise `max_steps` for that stage (or for the whole pipeline). There is no resume yet, so progress that lives in files is what you keep; re-run the stage by hand with `tether run --skill ...`.
+- **A stage's gate keeps failing.** Run the gate command by hand; make the stage goal name the file it must produce.
+- **Invalid manifest.** `Error: invalid pipeline ...` and exit code 1 name the field.
+
+More: [Gates, memory, pipelines](../tutorial/workflows-and-telemetry.md#pipelines), [multi-agent](../tutorial/multi-agent.md).

tether_sdk-0.2.9/docs/guides/add-your-own-tool.md

@@ -0,0 +1,62 @@
+# Give the model a tool of your own
+
+*For: Python developers who want the model to call their code. After this page you can turn a function into a tool, run it with a local model, and know what the model sees.*
+
+Tether exposes exactly one tool schema to the model, `act(cmd, stdin)`. Your function becomes a **command** behind it, so adding ten tools does not add ten schemas to the prompt.
+
+## The function
+
+```python
+import asyncio
+
+from tether import Harness, tool
+
+PRICES = {"apple": 0.5, "pear": 0.75, "melon": 3.2}
+
+
+@tool(name="price", description="Look up the unit price of a fruit")
+def price(fruit: str) -> str:
+    """Return the price of one `fruit` in euros. Known fruit: apple, pear, melon."""
+    if fruit not in PRICES:
+        return f"Unknown fruit `{fruit}`. Known: {', '.join(PRICES)}."
+    return f"{fruit}: {PRICES[fruit]:.2f} EUR"
+
+
+async def main() -> None:
+    harness = Harness(model="ollama/qwen3.5:9b", tools=[price])
+    session = await harness.run("What do 3 pears and 1 melon cost together? Use the price tool.")
+    print(session.status, "-", session.result)
+
+
+asyncio.run(main())
+```
+
+Type hints and the docstring become the command's usage text. The model only sees the one-line description until it runs `price --help` or calls it wrongly, so a tool costs about a dozen prompt tokens until it is used.
+
+## Run it
+
+```bash
+python shop.py
+```
+
+```text
+COMPLETED - 5.45 EUR
+```
+
+Ten seconds, three steps: the model asked for the pear price, then the melon price, then did the sum (3 × 0.75 + 3.20 = 5.45) and finished. Note what the tool does on bad input: it returns the list of valid fruit and does not raise. A message that says what to do next is how a small model recovers on its own.
+
+## Make the error message do the work
+
+Write tool errors for a reader that cannot ask a follow-up question: say what was wrong, list the valid options and show the next call. A tool that raises a stack trace teaches the model nothing.
+
+## Other ways to add things
+
+- **In a skill.** Put the function in `skills/<name>/tools.py` and list its name under `tools:` in `SKILL.md`; tools are opt-in, so an unlisted tool stays unavailable.
+- **A model backend, not a tool.** Declare it in `~/.tether/providers.yaml` or register a class: [Model providers](../reference/providers.md).
+
+## When it goes wrong
+
+- **`unknown command` for your tool.** It was not passed in `tools=[...]` (or not listed in the skill's `tools:`).
+- **The model passes the wrong argument.** Tether answers with the tool's usage line; if it keeps happening, tighten the docstring and the error message.
+
+More: [Python SDK and custom tools](../tutorial/sdk-and-custom-tools.md), [Extending tether](../extending.md).