tether-sdk 0.3.0__tar.gz → 0.3.1__tar.gz

{tether_sdk-0.3.0 → tether_sdk-0.3.1}/AGENTS.md

@@ -55,7 +55,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` (handed back as `WAITING_INPUT`, `send` resumes it with a fresh budget). A bare `done` (no answer, no stdin) completes with the result `Done.` and still runs the `verify` gates; `done --ask` with no question is an error (#169).
 - A bash command that needs approval to run outside the jail (#59) also pauses as `WAITING_INPUT` (`[APPROVAL NEEDED] <command>`, JSON `approval: {command, prefix}`); `send approve` runs it and resumes, any other reply refuses it.
 - 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`. A reply of 80 or more characters may be the answer: the nudge says it was not delivered and to pass it to `done`, and a session that still ends `WAITING_INPUT` (stuck or out of steps) carries the last such reply in its result, marked "never confirmed with `done`" (at most 2,000 chars, #173). Lookups by built-in tools (`web search|fetch`, `mem search|recall`, `agent status|wait|read|query`) count as reads, not changes.
-- After 6 consecutive read-only/verification steps following a change, the harness appends a `[NUDGE]` to that step's observation reminding the model to call `done` if the task is complete, repeated every 8 more quiet steps until the next change (0 static prompt tokens, #74, #132). Once per session, at 75% of `max_steps` (limits of 8 or more), a one-line `[NUDGE]` says how many steps are left (#133). 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 (#92) first get one `[WRAP UP]` turn (a read-only session is asked for its final answer, a session that already changed something is asked to call `done` with what is done and what is left, unless its `verify` gates or green test already finish it). Being stuck any way (the stall guard's warnings still unanswered after the wrap-up, or the same check command failing 3 times with an edit in between) restarts the session: one `restart` turn (event_type `restart`, at most 6000 chars: the files as the model left them, the last failing output, counts of what was tried; failed commands are not replayed) and the history continues from that turn alone. After 2 restarts, being stuck again hands the task back: the session ends `WAITING_INPUT` (exit code 2) with a `[STUCK ...]` summary as its result, so the caller can refine the request and `send` it. 0 static prompt tokens, no extra model call; `tether stop <id>` terminates a detached worker (#89). When that restart comes from the same check command failing 3 times, the files the model changed go back to how they started (a fresh attempt, Olausson et al. ICLR 2024) and the message names the failing tests instead of quoting the failed code; files it created stay. A run counts as near a pass when at most 3 tests fail (counted from the runner's summary line, so `| head` cannot hide failures) and more than twice that many pass: the harness keeps that version, and once 3 later runs fail to beat it, its files go back in place with one `[RESTORED]` line and the history stays (no restart turn, #173).
+- After 6 consecutive read-only/verification steps following a change, the harness appends a `[NUDGE]` to that step's observation reminding the model to call `done` if the task is complete, repeated every 8 more quiet steps until the next change (0 static prompt tokens, #74, #132). Once per session, at 75% of `max_steps` (limits of 8 or more), a one-line `[NUDGE]` says how many steps are left (#133); without a change it asks for the answer instead of an edit. The step before the limit gets a one-line `[LAST STEP]` notice, once (limits of 8 or more). 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); with neither `bash` nor `edit` enabled it asks for the answer or one more lookup. Seven reads of one file in a row with no change are a `cycle_stall`, and 4 stall warnings without a change (#92) first get one `[WRAP UP]` turn (a read-only session is asked for its final answer, a session that already changed something is asked to call `done` with what is done and what is left, unless its `verify` gates or green test already finish it). Being stuck any way (the stall guard's warnings still unanswered after the wrap-up, or the same check command failing 3 times with an edit in between) restarts the session: one `restart` turn (event_type `restart`, at most 6000 chars: the files as the model left them, the last failing output, counts of what was tried; failed commands are not replayed) and the history continues from that turn alone. After 2 restarts, being stuck again hands the task back: the session ends `WAITING_INPUT` (exit code 2) with a `[STUCK ...]` summary as its result, so the caller can refine the request and `send` it. 0 static prompt tokens, no extra model call; `tether stop <id>` terminates a detached worker (#89). When that restart comes from the same check command failing 3 times, the files the model changed go back to how they started (a fresh attempt, Olausson et al. ICLR 2024) and the message names the failing tests instead of quoting the failed code; files it created stay. A run counts as near a pass when at most 3 tests fail (counted from the runner's summary line, so `| head` cannot hide failures) and more than twice that many pass: the harness keeps that version, and once 3 later runs fail to beat it, its files go back in place with one `[RESTORED]` line and the history stays (no restart turn, #173).
 - 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. Before the first model call every gate is pre-checked (`tether/gates.py`): an empty gate, one that cannot be parsed, or a program that does not exist (every command of a `&&`/`||`/`;`/`|` chain; relative paths are looked up in the workspace) ends the session the same way with no tokens spent (#82). When the stall guard is about to restart or hand back a session 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). With no gates, the model's own last passing test run (runner-recognised, nothing changed since, still green when re-run) is the implicit gate, at a stall and at the step cap; a passing run after a change also appends a one-line `[NUDGE]` to call `done` (#177).
 
 ### Rule 4: Progressive `--help` (JIT Schema Disclosure)
@@ -75,6 +75,7 @@ Reviewers and the Team Leader cite the failing line when they reject a change.
 - Exception: the latest read of each of the last 8 files (`edit view <p>`, `bash cat/head/tail/sed -n <p>`; paths normalized against the workspace) is not folded until `<p>` is edited (`edit write|append|replace`, or any other bash command naming it: `sed -i`, `tee`, redirects, `python -c`) or re-read. The head+tail elision still applies (an observation may use up to a third of `max_context_tokens`, at least 2,400 chars), and under `max_context_tokens` pressure it is folded like any other (oldest first). The `mem recall` hint is shown only when `mem` is enabled (else "re-run the command").
 - A recognised test command piped to `head` (`<tests> 2>&1 | head -N`, nothing else piped) runs without the pipe and is cut by `bash` itself: first N lines, a `[... K lines cut by head ...]` marker, the last 6 lines and the tests' own `[exit N]`, so the summary and exit code survive (0 static prompt tokens, #173).
 - When a recognised test command fails, the harness appends the source of up to 3 failing test functions named in the traceback (`[failing test source]`, workspace files only, at most 1,500 chars, skipped when the output already shows it) so the model sees the test's inputs (0 static prompt tokens, no model call, #173). When the same suite ran before (same test count) and tests that passed then fail now, one `[regression]` line names them and the newly passing ones (at most 5 names each, 400 chars, #173). When a command that writes existing workspace files (`edit write|replace <p>`, `> p`, `>> p`, `tee p`) leaves all of them with the same code (identical bytes, or for `.py` an identical AST), one `[NUDGE]` line says so (`tether/unchanged.py`, at most 200 chars, 0 static prompt tokens, #173). A whole-file rewrite (`edit write p`, `> p`) of a file of 20 or more lines that changed at most 20% of them gets one `[NUDGE]` pointing to `edit replace p`, once per file per session (#173).
+- A `bash` command that leaves a workspace `.py` file unparsable (it parsed before the command) is undone: the old bytes are written back and one `[REVERTED]` line per file (at most 3) says so, before the auto-test and the notes run (F5, `tether/unchanged.py` `broken_by_command`, 0 static prompt tokens, no model call). `edit` commands are not reverted (`edit` warns on its own).
 - Repair loop around tests (#173, 0 static prompt tokens, no model call): once the model has run a recognised test command, the harness re-runs it after each command that writes an existing workspace file and appends the result (`[auto-test]`, Aider's auto-test), so no version is typed blind. When the model first reads the test file of a starting file (`x_test.py`/`test_x.py` next to `x.py`), one `[BEFORE WRITING]` line asks it to state in plain words what the 3 hardest tests call and expect (AlphaCodium, Ridnik et al. 2024); a plain-text reply then is the expected answer, not a nudge. If it writes first, that first rewrite is held once with the same question. When the same tests fail again after a change, or at most 3 fail, a runtime trace of the smallest failing test is appended once per failing set (`tether/trace.py`: calls into workspace code with arguments and results, 2 levels deep, at most 30 lines / 1,500 chars; LDB, Zhong et al. ACL 2024). The first near pass also gets one `[NUDGE]` pointing to `edit replace`.
 - History is replayed as structured `tool_calls` + `tool` results (providers with `structured_history = True`; textual `act('...')` form only as fallback), with `stdin` replayed as a real 400-char prefix, never a `<N chars>` placeholder. A call and its result are trimmed together.
 
@@ -130,7 +131,7 @@ tether/
     ├── done.py          # Mandatory explicit completion command (`done`)
     ├── bash.py          # Kernel-sandboxed, env-scrubbed, workspace-bounded shell execution
     ├── web.py           # Zero-config DuckDuckGo Lite httpx search (+ Brave/Tavily/SearXNG env override) & reader
-    ├── edit.py          # Workspace-jailed file viewing (`view`) & stdin patching (`write`, `append`, `replace`)
+    ├── edit.py          # Workspace-jailed file viewing (`view`) & stdin patching (`write`, `append`, `insert`, `replace`)
     ├── mem.py           # Working scratchpad (`pin`/`unpin`), FTS5 search (`search`), & recall (`recall`)
     └── agent.py         # Async multi-agent orchestration (`spawn`, `status`, `wait`, `query`, `read`, `send`)
 ```
@@ -234,7 +235,7 @@ uv run mypy tether/
 2. **Async-First Design:**
    - 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`), rewriting `edit --file p --content c` flags into `edit write p` + stdin (and `edit write p <text>` with no stdin into `edit write p` + `<text>` as typed) and `done --stdin 'x'` into `done` + stdin, unwrapping `bash -c/-lc '<cmd>'` and `sh -c` wrappers, unwrapping an `act("<cmd>", stdin="...")` call typed as text in `cmd` (also after `bash`) into the command and its `stdin` (#169), running an unknown first word through the enabled `bash` tool (never for disabled built-ins), running a bash `cd <missing dir> && <cmd>` as `<cmd>` in the workspace with a one-line note (#79), running plain shell file writes/reads as `edit` when `edit` is on and `bash` is off (`echo t > p`, `printf t > p`, `cat > p` + heredoc -> `edit write p`, with `>>` -> `edit append p`; `cat p` -> `edit view p`), registering extra quirk fixers with `register_normalizer`, mapping a native tool call named other than `act` (also written as plain-text JSON `{"name": ..., "arguments": {...}}`) 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.
+   - 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`), rewriting `edit --file p --content c` flags into `edit write p` + stdin (and `edit write p <text>` with no stdin into `edit write p` + `<text>` as typed) and `done --stdin 'x'` into `done` + stdin, unwrapping `bash -c/-lc '<cmd>'` and `sh -c` wrappers, unwrapping an `act("<cmd>", stdin="...")` call typed as text in `cmd` (also after `bash`) into the command and its `stdin` (#169), running an unknown first word through the enabled `bash` tool (never for disabled built-ins), running a bash `cd <missing dir> && <cmd>` as `<cmd>` in the workspace with a one-line note (#79), moving a path typed inside the quotes of `sed -n 'a,bp file'` out of them (#270), running plain shell file writes/reads as `edit` when `edit` is on and `bash` is off (`echo t > p`, `printf t > p`, `cat > p` + heredoc -> `edit write p`, with `>>` -> `edit append p`; `cat p` -> `edit view p`), registering extra quirk fixers with `register_normalizer`, mapping a native tool call named other than `act` (also written as plain-text JSON `{"name": ..., "arguments": {...}}`) 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 `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:**

{tether_sdk-0.3.0 → tether_sdk-0.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: tether-sdk
-Version: 0.3.0
+Version: 0.3.1
 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

tether_sdk-0.3.1/docs/guides/small-models.md

@@ -0,0 +1,88 @@
+# Write tasks a small model can finish
+
+*For: people who hand tasks to tether on a small local model, and people choosing a model for a job. After this page you can write a task that a 9B model finishes, check that it really did, and tell whose fault a failed task is.*
+
+A small model is a good typist and a careful rule follower. It is a weak planner. So the plan goes in the task text, and the model does one small thing at a time.
+
+## The rules
+
+1. **One edit per task.** One file, one place. Two changes are two tasks.
+2. **Say where.** Name the file and the line numbers, and tell the model to view those lines first.
+3. **Give a contract, not code.** Say what the function must return and show two or three examples. The model writes the body. If you already wrote the code, apply it yourself.
+4. **Avoid line arithmetic.** New code goes in with `edit append <file>`, which needs no line numbers. To add lines in the middle, replace one short line with itself first and the new lines after it.
+5. **Pass the edit as two arguments.** `cmd` is `edit replace <file> --lines A:B` and `stdin` is the final text of those lines. No diff marks, no code fences.
+6. **One check that runs code.** Give one command that fails before the change and passes after it. Compare exact values. A `grep` for a word passes on broken code.
+7. **Keep chores out.** Lint, types and the full test suite run after the task, by you or by `--verify`.
+8. **Small step budget.** `--max-steps 8` to `12`. A task that needs more is two tasks.
+
+## Example
+
+A function forgets to add 32. This is `temps.py`:
+
+```python
+def to_fahrenheit(celsius):
+    return celsius * 9 / 5
+```
+
+`check.py` fails now and passes after the fix:
+
+```python
+from temps import to_fahrenheit
+
+assert to_fahrenheit(0) == 32
+assert to_fahrenheit(100) == 212
+assert to_fahrenheit(-40) == -40
+print("ok")
+```
+
+The task, in `task.md`:
+
+```text
+You do ONE small edit. Follow the steps in order. Do nothing else.
+1. View: `edit view temps.py --lines 1:2`. Line 2 returns the wrong value: it forgets to add 32.
+2. Fix line 2 so `to_fahrenheit(0)` is 32 and `to_fahrenheit(100)` is 212. Call the `act` tool with two arguments: cmd = `edit replace temps.py --lines 2:2`, stdin = the corrected line (4 spaces of indentation).
+3. Run `bash python3 check.py`. It prints `ok` -> call `act("done", stdin="fixed")`. It fails -> view line 2, fix it the same way, run the check again.
+```
+
+Run it:
+
+```bash
+tether run --model ollama/qwen3.5:9b --tools bash,edit --max-steps 8 --verify "python3 check.py" "$(cat task.md)"
+```
+
+```text
+session ses_3353ac87
+fixed
+```
+
+The session took 4 of its 8 steps. `--verify` ran `check.py` again before `done` was accepted, so `fixed` means the check passed, not that the model said so.
+
+## What we saw, by model
+
+| Model | Does well | Does badly |
+|---|---|---|
+| `ollama/qwen3.5:9b` | Follows numbered steps exactly. Writes a short function body from a contract. Writes a test from a described case. Fixes its own code when the check fails. | Counting lines after an edit. Long tasks with several goals. Side rules such as a line-length limit. It follows a wrong task as faithfully as a right one. |
+| `ollama/qwen3.5:4b` | Single one-line edits. | Leaves the steps and does something else often enough that we do not rely on it. |
+| Claude Haiku | Plans, tests written before the code, QA and review of a finished change. | Writing tasks for a smaller model: wrong line counts, checks that could not fail. Its tests need a second look. |
+| Claude Sonnet, Claude Opus | No data yet for this way of working. | No data yet. |
+
+This table changes as tether and the models change. A row is added only from runs we looked at.
+
+## When it goes wrong
+
+Read the session with `tether export <id>` and ask three questions, in this order:
+
+1. **Did a tool refuse or mangle a correct command?** That is tether. Look for an error after a command that looks right, and report it.
+2. **Did the model do what the task said, and the result is still wrong?** That is the task. Fix the text: a wrong line number, a missing step, a check that cannot fail.
+3. **Did the model leave a clear task?** That is the model. Make the task smaller once. If it still leaves it, use a larger model for that task.
+
+Common signs:
+
+| Sign | Likely cause | What to do |
+|---|---|---|
+| Out of steps, many views and replaces of the same lines | Line arithmetic | Use `edit append`, or replace one short line |
+| `done`, but the file is broken | The check did not run the code | Make the check import and call it |
+| The check passes, the output is slightly off | The check compares part of the output | Compare the whole value |
+| An edit command is refused | The edit text was put inside `cmd` | Say "two arguments: cmd and stdin" in the task |
+
+More: [Fix a failing test with a local model](fix-a-failing-test.md), [Troubleshooting](../troubleshooting.md).

{tether_sdk-0.3.0 → tether_sdk-0.3.1}/docs/index.md

@@ -18,6 +18,7 @@ Most agent frameworks drown small models in 3,000–8,000 tokens of nested JSON
 | I want to... | Read |
 |---|---|
 | Have a small local model fix a failing test | [Fix a failing test](guides/fix-a-failing-test.md) |
+| Write a task a small model can finish | [Write tasks a small model can finish](guides/small-models.md) |
 | Delegate work from Claude Code, Codex or Cursor | [Use tether from your agent](guides/use-tether-from-your-agent.md) |
 | Check my setup before the first run | `tether doctor` in the [CLI reference](reference/cli.md) |
 | Let a session work on its own branch | [Run a session on its own branch](guides/own-branch.md) |

{tether_sdk-0.3.0 → tether_sdk-0.3.1}/docs/llms.txt

@@ -5,6 +5,7 @@
 ## Start here
 - [Home](https://igormcsouza.github.io/tether/): what tether is, install, first run.
 - [Fix a failing test with a local model](https://igormcsouza.github.io/tether/guides/fix-a-failing-test/): a verification gate decides when the job is done.
+- [Write tasks a small model can finish](https://igormcsouza.github.io/tether/guides/small-models/): task-writing rules, a re-runnable example, what each model does well and badly.
 - [Use tether from Claude Code, Codex or Cursor](https://igormcsouza.github.io/tether/guides/use-tether-from-your-agent/): MCP setup, the JSON result, exit codes.
 - [A pipeline where each stage has its own job](https://igormcsouza.github.io/tether/guides/a-pipeline-with-checks/): stages, per-stage model, tools and gate.
 - [Give the model a tool of your own](https://igormcsouza.github.io/tether/guides/add-your-own-tool/): turn a Python function into a command.

{tether_sdk-0.3.0 → tether_sdk-0.3.1}/docs/reference/providers.md

@@ -123,6 +123,7 @@ A `command` entry wraps any program that takes a prompt and prints JSON.
 
 - **Placeholders**: `{model}`, `{system}`, `{conversation}` and `{schema}` (the act JSON schema, compact) are substituted in `argv` items and in the `stdin` template. If `stdin` is omitted it defaults to `{conversation}`.
 - **No shell**: `argv` is executed directly, never through a shell.
+- **Failures**: a non-zero exit with output fails the session at once with ``Worker error: ProviderError: command provider `<model>` failed (exit N): <text>``. The text is the provider's own words: the `reply` field when the output is JSON, else its stdout or stderr, at most 300 characters. It is not retried, so a usage or rate limit costs one call: wait for the reset or pass another `--model`.
 - **Retries**: a timeout, or a non-zero exit with no output, is retried twice with 1 s then 2 s backoff; after the third failure Tether raises `ProviderError` naming the provider, model and timeout. A non-zero exit with output, or an unparsable reply, is not retried.
 - **Reply**: `reply` is a dotted path into the JSON the command prints (`result` in the example).
 - **Usage**: `usage.prompt` is a path or a list of paths (their values are summed); `usage.completion` is a path. Both are optional.

{tether_sdk-0.3.0 → tether_sdk-0.3.1}/docs/release-notes.md

@@ -1,5 +1,28 @@
 # Release Notes
 
+## v0.3.1 (2026-11-14)
+
+### Added
+
+- `edit insert <path> --line N` adds the stdin lines before line N and replaces nothing, so a small model no longer loses line N when it adds lines (#320). A bare `edit replace <path> --lines a:b` with empty stdin now says it deleted the lines (#321), and `edit append` and `insert` always end the file with a newline.
+
+### Fixed
+
+- A session whose only edits were refused (wrong command shape, sandbox refusal) is no longer ended as `COMPLETED` "Finished by the harness ... after its change": a refused command ran nothing, so it does not count as a change and the session is handed back as `WAITING_INPUT` (#318).
+- `edit replace <path>` now applies a unified diff or bare `@@` hunks sent as stdin through the same applier as `edit <path>`; a `, stdin="..."` tail typed inside the command is moved into stdin; and `edit replace <path> --lines a:b` applies a marked `-`/`+` diff of exactly those lines, so a correct edit is no longer refused or mis-applied (#317).
+- A headless worker no longer imports workspace code through a relative or empty `PYTHONPATH` entry: only absolute entries are passed on (#283).
+- The sandbox no longer fails every `bash` call with `bwrap: Can't create file at /run/...` when `/run` holds a symlink to a unix socket (e.g. `/run/php/php-fpm.sock`): the socket the link points to is masked, once.
+- `sed -n '45,90p file'` (the path typed inside the quotes) now runs as `sed -n '45,90p' file` instead of failing (#270).
+- A `command` provider that hits a usage or rate limit now fails at once with the provider's own words and a next step (`wait for the reset or pass another --model`), instead of a raw JSON error after retries (#305).
+- A `bash` command that times out after starting a background job (`server &`) now says why and what to do: run it in the foreground with `timeout N <cmd>`, or send its output away with `<cmd> >/dev/null 2>&1 &` (#319).
+- `web search` now says when the search engine refuses (HTTP 202 or a bot-check page) instead of printing `No search results found.`, so a model stops retrying. `web fetch <url>#anchor` starts the returned text at that element, and `web fetch <url> --from <text>` starts it at the first match. A cut page names the `--from` words to continue with.
+- The harness tells a session that only looks things up to answer, not to edit: the step before the limit gets a `[LAST STEP]` notice, the 75% and 12-step nudges ask for an answer when neither `bash` nor `edit` is enabled, and a restart or failed `verify` gate after a check failed 3 times names `done --ask` as the way out of a wrong test.
+- A `bash` command that leaves a Python file unparsable is undone: the file goes back to its bytes from before the command, and the observation names it in a `[REVERTED]` line so the model redoes the change in smaller steps (F5).
+
+### Docs
+
+- New guide [Write tasks a small model can finish](guides/small-models.md): the task-writing rules, a re-runnable example, what each model was seen to do well and badly, and how to tell whose fault a failed task is.
+
 ## v0.3.0 (2026-11-09)
 
 ### Breaking changes

{tether_sdk-0.3.0 → tether_sdk-0.3.1}/docs/tutorial/built-in-tools.md

@@ -37,6 +37,8 @@ act(cmd="bash", stdin="python3 - << 'EOF'\nimport math\nprint(math.pi)\nEOF")
 
 A test run piped to `head` (`python3 -m unittest 2>&1 | head -50`) still shows how it ended: tether keeps the first lines, marks what it cut, and adds the last lines with the summary and the tests' own exit code.
 
+A command that times out after starting a background job (`server &`) gets one more line saying so, with the two fixes: run it in the foreground with `timeout N <cmd>`, or send its output away with `<cmd> >/dev/null 2>&1 &`.
+
 ## `edit` — Workspace-Jailed File Operations
 
 Provides deterministic line-numbered viewing and `stdin`-based writing/replacement without sed/awk quoting bugs:
@@ -62,8 +64,12 @@ Zero-config web search via DuckDuckGo Lite (or automatic override via `SEARXNG_U
 ```text
 act(cmd='web search "SQLite WAL concurrency" --max 5')
 act(cmd="web fetch https://www.sqlite.org/wal.html")
+act(cmd="web fetch https://docs.python.org/3/library/stdtypes.html#str.splitlines")
+act(cmd="web fetch https://www.sqlite.org/wal.html --from 'checkpoint'")
 ```
 
+`#anchor` starts the text at that element, `--from <text>` at the first match; a cut page prints the `--from` words to continue with.
+
 ## `mem` — Pinned Scratchpad & BM25 Observation Recall
 
 When raw tool outputs age past $K=2$ turns and the history fills more than half of the context budget, Tether folds them into 1-line tombstones (`[obs_3 folded: ...]`). The `mem` tool lets the agent pin key facts into active context or search/recall folded observations from SQLite FTS5:
@@ -89,7 +95,7 @@ act(cmd="mem recall obs_3")
 
 The [course-builder example](https://github.com/igormcsouza/tether/tree/main/examples/course) uses `edit` and custom tools to turn a plan into a course. Three limits shaped it:
 
-- **`edit write` replaces the whole file.** Overwriting an existing file now reports `Replaced N lines with M (X removed, Y added; first removed: ...)` and, when the file shrank, points to `edit replace --lines a:b` ([#40](https://github.com/igormcsouza/tether/issues/40)). Small models assume it appends and silently lose earlier content. To build a file in parts, use `edit append <path>` with the next part in `stdin`; it creates the file if needed and adds a newline when the file does not end with one.
+- **`edit write` replaces the whole file.** Overwriting an existing file now reports `Replaced N lines with M (X removed, Y added; first removed: ...)` and, when the file shrank, points to `edit replace --lines a:b` ([#40](https://github.com/igormcsouza/tether/issues/40)). Small models assume it appends and silently lose earlier content. To build a file in parts, use `edit append <path>` with the next part in `stdin`; it creates the file if needed and adds a newline when the file does not end with one. To add lines in the middle, use `edit insert <path> --line N` with the lines in `stdin`: they go before line N and nothing is replaced (N = lines + 1 appends).
 - **`web search` cannot reliably find a specific YouTube video.** Use a [custom tool](sdk-and-custom-tools.md#pattern-numbered-candidates) that returns numbered candidates instead.
 - **Tools are opt-in.** The searcher skill lists `tools: [yt-todo, yt-candidates, yt-save]` and nothing else; `edit` is only loaded by the stages that write files.
 

tether_sdk-0.3.1/e2e/test_bash_background.py

@@ -0,0 +1,15 @@
+"""#319: a timed-out background job says why. Scripted: the replies never depend on the model."""
+
+from __future__ import annotations
+
+from e2e.conftest import Tether
+
+HINT = "A background job (`&`) keeps the command open."
+
+
+def test_timed_out_background_job_says_why(tether: Tether, chaos) -> None:
+    # one 30 s wait: the sandbox kills the job at the timeout; the result must carry the hint
+    chaos.script(("bash sleep 60 & wait", None), ("done", "finished"))
+    r = tether.run("background", "--tools", "bash", "--max-steps", "4")
+    outputs = tether.tool_outputs(r["id"])
+    assert any("command timed out" in o and HINT in o for o in outputs), outputs

tether_sdk-0.3.1/e2e/test_broken_python.py

@@ -0,0 +1,30 @@
+"""F5: a bash command that breaks a Python file is undone and the model is told.
+
+Scripted: the replies are fixed, so the result never depends on what the model answers.
+"""
+
+from __future__ import annotations
+
+from e2e.conftest import Tether
+
+GOOD = "def f(x):\n    return x + 1\n"
+
+
+def test_a_bash_write_that_breaks_python_is_undone(tether: Tether, chaos) -> None:
+    # the first command leaves m.py unparsable (a printf escape gone wrong); the harness must put
+    # the old bytes back before the model's next step
+    chaos.script(
+        ("printf 'def f(x):\\n    return x +\\n' > m.py", None),
+        ("ls", None),
+    )
+    (tether.ws / "m.py").write_text(GOOD)
+    tether.run("broken", "--tools", "bash", "--max-steps", "2")
+    assert (tether.ws / "m.py").read_text() == GOOD
+
+
+def test_a_sed_i_that_breaks_python_is_undone(tether: Tether, chaos) -> None:
+    # sed -i is not a redirect: the file is found because the command names it
+    chaos.script(("sed -i 's/return x/return (x/' m.py", None), ("ls", None))
+    (tether.ws / "m.py").write_text(GOOD)
+    tether.run("broken", "--tools", "bash", "--max-steps", "2")
+    assert (tether.ws / "m.py").read_text() == GOOD

tether_sdk-0.3.1/e2e/test_edit_insert.py

@@ -0,0 +1,14 @@
+"""#320: `edit insert` adds lines without replacing the kept line. Scripted: the proxy forces the
+edit calls, so the result never depends on what the model answers."""
+
+from __future__ import annotations
+
+from e2e.conftest import Tether
+
+
+def test_scripted_insert_keeps_every_line(tether: Tether, chaos) -> None:
+    # one insert before line 2, then the run ends at the step limit
+    chaos.script(("edit insert f.txt --line 2", "X\n"), *[("edit view f.txt", None)] * 12)
+    (tether.ws / "f.txt").write_text("a\nb\nc\n")
+    tether.run("insert", "--tools", "edit", "--verify", "true", "--max-steps", "10")
+    assert (tether.ws / "f.txt").read_text() == "a\nX\nb\nc\n"

tether_sdk-0.3.1/e2e/test_edit_shapes.py

@@ -0,0 +1,15 @@
+"""#317: a correct diff sent to `edit replace <path>` is applied. Scripted: the proxy answers
+with a fixed command, so the result never depends on what the model says."""
+
+from __future__ import annotations
+
+from e2e.conftest import Tether
+
+DIFF = "@@ -1,3 +1,3 @@\n x = 1\n-y = 2\n+y = 20\n z = 3\n"
+
+
+def test_diff_sent_to_replace_is_applied(tether: Tether, chaos) -> None:
+    chaos.script(("edit replace f.py", DIFF))
+    (tether.ws / "f.py").write_text("x = 1\ny = 2\nz = 3\n")
+    tether.run("shapes", "--tools", "edit", "--verify", "true", "--max-steps", "3")
+    assert (tether.ws / "f.py").read_text() == "x = 1\ny = 20\nz = 3\n"

tether_sdk-0.3.1/e2e/test_last_step.py

@@ -0,0 +1,19 @@
+"""F3 last-step notice: a scripted lookup-only session is told on its last-but-one step to answer.
+
+Scripted replies, so the result never depends on the model.
+"""
+
+from __future__ import annotations
+
+from e2e.conftest import Tether
+
+
+def test_last_step_notice_reaches_a_lookup_only_session(tether: Tether, chaos) -> None:
+    # 9 lookups within 10 steps: the notice lands on step 9, the one before the limit
+    chaos.script(*[f"ls {i}" for i in range(9)])
+    r = tether.run("look around", "--tools", "bash", "--max-steps", "10")
+    outs = tether.tool_outputs(r["id"])
+    notices = [o for o in outs if "[LAST STEP]" in o]
+    assert len(notices) == 1, outs[-3:]
+    assert "Call `done` now with your answer" in notices[0]
+    assert r["rc"] in (0, 2), r

tether_sdk-0.3.1/e2e/test_provider_limit.py

@@ -0,0 +1,39 @@
+# Provider usage limit (#305), end to end: a command provider reports its usage limit.
+# Scripted: no model is used; the command is a local script.
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+import yaml
+
+from e2e.conftest import Tether
+
+LIMIT = """import json, os, sys
+counter = sys.argv[1]
+n = int(open(counter).read()) if os.path.exists(counter) else 0
+open(counter, "w").write(str(n + 1))
+sys.stdin.read()
+print(json.dumps({"is_error": True, "result": "Claude usage limit reached. Resets 1:30pm"}))
+sys.exit(1)
+"""
+
+
+def test_usage_limit_fails_at_once_with_provider_words(tether: Tether, tmp_path: Path) -> None:
+    counter = tmp_path / "counter"
+    script = tmp_path / "limit.py"
+    script.write_text(LIMIT)
+    providers = tmp_path / "providers.yaml"
+    entry = {
+        "kind": "command",
+        "argv": [sys.executable, str(script), str(counter)],
+        "stdin": "{conversation}",
+        "reply": "result",
+    }
+    providers.write_text(yaml.safe_dump({"e2elimit": entry}))
+    r = tether.run("answer", prefix="e2elimit")
+    assert r["status"] == "FAILED", r
+    assert "usage limit reached" in r["failure"]["message"], r
+    assert "--model" in r["failure"]["message"], r
+    assert counter.read_text() == "1", "a usage limit is not retried"

tether_sdk-0.3.1/e2e/test_refused_not_a_change.py

@@ -0,0 +1,16 @@
+"""#318: a refused command is not a change. Scripted: the proxy forces refused edits (no stdin),
+so the result never depends on the model; the session must end WAITING_INPUT, not COMPLETED."""
+
+from __future__ import annotations
+
+from e2e.conftest import Tether
+
+
+def test_refused_edits_do_not_finish_as_completed(tether: Tether, chaos) -> None:
+    # 12 refused edits outlast the 10 steps: the stall guard must not finish on the green gate
+    chaos.script(*[("edit replace f.py --lines 1:1", None)] * 12)
+    (tether.ws / "f.py").write_text("x = 1\n")
+    r = tether.run("refused", "--tools", "edit", "--verify", "true", "--max-steps", "10")
+    assert (tether.ws / "f.py").read_text() == "x = 1\n"
+    assert (r["rc"], r["status"]) == (2, "WAITING_INPUT"), r
+    assert "Finished by the harness" not in (r["result"] or ""), r

tether_sdk-0.3.1/e2e/test_sed_quoted_path.py

@@ -0,0 +1,14 @@
+"""sed -n 'a,bp file' with the path typed inside the quotes runs as sed -n 'a,bp' file (#270)."""
+
+from __future__ import annotations
+
+from e2e.conftest import Tether
+
+
+def test_sed_with_path_inside_quotes_runs(tether: Tether, chaos) -> None:
+    (tether.ws / "f.txt").write_text("one\ntwo\nthree\n")
+    chaos.script("sed -n '1,2p f.txt'", ("done", "ok"))
+    r = tether.run("show the first lines of f.txt", "--tools", "bash")
+    out = tether.tool_outputs(r["id"])[0]
+    assert "one" in out and "two" in out
+    assert "extra characters" not in out

tether_sdk-0.3.1/e2e/test_web_fetch_anchor.py

@@ -0,0 +1,18 @@
+"""F2: a fetch with #anchor and --from that cannot run is reported, not crashed.
+
+Scripted: replies are fixed, so the result never depends on the model.
+"""
+
+from __future__ import annotations
+
+from e2e.conftest import Tether
+
+
+def test_bad_fetch_with_anchor_and_from_reports_error(tether: Tether, chaos) -> None:
+    # ftp is refused before any network I/O, so the scenario is deterministic offline
+    fetch = "web fetch ftp://example.org/page#top --from intro"
+    chaos.script((fetch, None), ("done", "stopped"))
+    r = tether.run("fetch", "--tools", "web", "--max-steps", "5")
+    assert r["rc"] == 0, r
+    outputs = tether.tool_outputs(r["id"])
+    assert any("URL must start with http:// or https://" in o for o in outputs), outputs

tether_sdk-0.3.1/e2e/test_worker_pythonpath_e2e.py

@@ -0,0 +1,31 @@
+"""#283: a headless worker with empty and relative PYTHONPATH entries still runs (scripted)."""
+
+from __future__ import annotations
+
+import subprocess
+import sys
+
+from e2e.conftest import Tether
+
+
+def _cli(t: Tether, env: dict[str, str], *args: str) -> subprocess.CompletedProcess[str]:
+    return subprocess.run(
+        [sys.executable, "-P", "-m", "tether.cli", *args],
+        cwd=t.ws,
+        env=env,
+        capture_output=True,
+        text=True,
+        timeout=120,
+    )
+
+
+def test_headless_run_survives_empty_and_relative_pythonpath(tether: Tether, chaos) -> None:
+    chaos.script(("done", "ok"))
+    dirty = dict(tether.env)
+    dirty["PYTHONPATH"] = ":."
+    p = _cli(tether, dirty, "run", "--headless", "--model", "e2e/scripted", "go")
+    sid = p.stdout.strip()
+    assert p.returncode == 0 and sid.startswith("ses_"), p.stderr
+    assert _cli(tether, tether.env, "wait", sid).returncode == 0
+    r = _cli(tether, tether.env, "read", sid)
+    assert "ok" in r.stdout, r.stdout + r.stderr

{tether_sdk-0.3.0 → tether_sdk-0.3.1}/mkdocs.yml

@@ -98,6 +98,7 @@ nav:
       - A pipeline where each stage has its own job: guides/a-pipeline-with-checks.md
       - Give the model a tool of your own: guides/add-your-own-tool.md
       - Run a session on its own branch: guides/own-branch.md
+      - Write tasks a small model can finish: guides/small-models.md
       - tutorial/index.md
       - CLI and Headless Sessions: tutorial/cli-and-headless.md
       - Python SDK and Custom Tools: tutorial/sdk-and-custom-tools.md