tether-sdk 0.2.1__tar.gz → 0.2.3__tar.gz

{tether_sdk-0.2.1 → tether_sdk-0.2.3}/AGENTS.md

@@ -33,13 +33,14 @@ Tether implements the architectural principles from *"LLM-Native Applications as
 - Sessions do **not** terminate simply because the model emitted a text response without a tool call (small 9B models frequently "think out loud" before acting).
 - 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`.
-- 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).
+- 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.
 
 ### 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**).
 - Full parameter signatures, defaults, and docstrings are revealed **Just-In-Time (JIT)** when:
   1. The model explicitly runs `<cmd> --help`, OR
   2. The model invokes `<cmd>` with missing/invalid arguments (self-healing error response, never an unhandled Python exception).
+  3. The model invokes a built-in tool that is not enabled: the error says it is disabled, lists the enabled tools and how to enable more (error responses are history, never prefix).
 - Auto-generated `--help` output must remain ultra-compact (**≤ 60 tokens** per command).
 
 ### Rule 5: Ephemeral Observation Folding
@@ -48,6 +49,7 @@ Tether implements the architectural principles from *"LLM-Native Applications as
   ```text
   [obs_3 folded: `web fetch https://...` (3,420 chars) | use `mem recall obs_3` to expand]
   ```
+- Exception: the latest read of each of the last 4 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|replace`, or any other bash command naming it: `sed -i`, `tee`, redirects, `python -c`) or re-read. The 2,400-char head+tail elision still applies, and the hard context budget remains #81. The `mem recall` hint is shown only when `mem` is enabled (else "re-run the command").
 - 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.
 
 ### Rule 6: Deterministic Security Envelope (Never Trust the LLM for Safety)
@@ -70,7 +72,7 @@ Tether implements the architectural principles from *"LLM-Native Applications as
 ```text
 tether/
 ├── __init__.py          # Public SDK exports: Harness, Pipeline, Session, Skill, SandboxPolicy, tool
-├── cli.py               # Headless-capable CLI: `tether run|pipeline|status|read|query|send|list|wait|stats|retro|events|mcp` (`--json` + documented exit codes)
+├── cli.py               # Headless-capable CLI: `tether run|pipeline|status|read|query|send|list|wait|stats|retro|events|misses|mcp` (`--json` + documented exit codes)
 ├── harness.py           # Control Plane: bounded agent loop, pipelines, SQLite inbox, worker spawn
 ├── pipeline.py          # Workflow Plane: declarative multi-stage YAML pipelines & model routing
 ├── api.py               # Agent-facing JSON session view, exit codes, events (`--json`)
@@ -82,7 +84,7 @@ tether/
 ├── multiplexer.py       # Action Plane: `act(cmd, stdin)` parser, command registry, JIT --help
 ├── decorator.py         # `@tool` introspection: converts Python type hints + docstrings to CLI specs
 ├── context.py           # State Plane: ContextAssembler, EphemeralFolder, token estimator
-├── skills.py            # Skill loader: Markdown + YAML frontmatter + optional sibling `tools.py`
+├── skills.py            # Skill loader: Markdown + YAML frontmatter + optional sibling `tools.py` (its tools must be listed in `tools:`)
 ├── providers/
 │   ├── base.py          # Abstract async ModelProvider protocol (`generate(messages, tools)`)
 │   ├── ollama.py        # Native Ollama `/api/chat` httpx adapter (`num_ctx`, `keep_alive`)
@@ -103,15 +105,15 @@ tether/
 - Default DB path: `.tether/tether.db` (configurable via `TETHER_DB` or `Harness(db_path=...)`) with `PRAGMA journal_mode=WAL;`.
 - Tables:
   - `sessions`: `id`, `parent_id`, `status` (`PENDING`, `RUNNING`, `WAITING_INPUT`, `COMPLETED`, `FAILED`), `model`, `skill`, `tools_json`, `sandbox_json`, `goal`, `result`, `step_count`, `max_steps`, `peak_tokens`, `total_prompt_tokens`, `total_completion_tokens`, `pid`, `created_at`, `updated_at`.
-  - `turns`: `id`, `session_id`, `step`, `role`, `content`, `tool_cmd`, `tool_stdin`, `obs_id`, `prompt_tokens`, `completion_tokens`, `duration_ms`, `event_type` (`ok` | `nudge` | `loop_stall` | `syntax_error` | `tool_error` | `gate_fail` | `completed`), `created_at`.
+  - `turns`: `id`, `session_id`, `step`, `role`, `content`, `tool_cmd`, `tool_stdin`, `obs_id`, `prompt_tokens`, `completion_tokens`, `duration_ms`, `event_type` (`ok` | `nudge` | `loop_stall` | `cycle_stall` | `syntax_error` | `tool_error` | `gate_fail` | `gate_error` | `completed`), `created_at`.
   - `observations`: `id`, `session_id`, `step`, `cmd`, `raw_output`, `summary`, `char_len`.
   - `chunks_fts` *(SQLite FTS5 Virtual Table)*: `session_id`, `source_type` (`result` | `observation` | `pin`), `source_id`, `chunk_index`, `content` — automatically indexes ~150-token paragraph/heading chunks of all observations, pins, and final `done` deliverables for sub-millisecond BM25 RAG (including cross-session project search via `mem search --project <query>`).
   - `pins`: `session_id`, `key`, `value` (supports session-scoped working memory and workspace-wide semantic facts under `GLOBAL_SESSION_ID = "__project__"` via `mem pin --project <key> <val>`).
   - `inbox`: `id`, `session_id`, `message`, `consumed` (`0` or `1`), `created_at`.
 - **Agent-to-Agent Interface (`api.py`, `mcp.py`):** `--json` outputs (schema `v: 1`), exit codes `0` completed / `1` usage / `2` waiting / `3` gate / `4` max steps / `5` worker error, failure text on stderr, `--result-file`, `--output-schema`, `tether events`. `tether mcp` serves the same JSON over stdio and requires the optional `tether-sdk[mcp]` extra (official `mcp` SDK, imported lazily so core stays dependency-light; Rule 7 allows it as an extra only); its sandbox is always rooted at `--workspace` and callers can only narrow it. Details: `docs/reference/agent-interface.md`.
 - **Telemetry & Failure-Mode Inspector (`tether stats`):**
-  - `tether stats [--model <m>] [--skill <s>] [--limit <n>]` aggregates per-model pass rates, cumulative token economy (`total_prompt_tokens + total_completion_tokens`), step latency, and self-healing ACI friction (`nudge`, `loop_stall`, `syntax_error`, `tool_error`, `gate_fail`), plus a top-offenders breakdown by tool command.
-- **Post-Mortem Distillation (`tether retro <session_id> [--apply] [--model <m>]`):** offline only (never mutates a live prompt). `store.extract_friction_trace` pulls `inbox` corrections and `loop_stall`/`syntax_error`/`tool_error`/`gate_fail` turns (+ the fixing command); one bounded LLM pass yields ≤2 rules (≤30 tokens each, deduped against existing rules). Prints a unified diff of `SKILL.md`; `--apply` appends under `## Learned Rules` (or pins to project memory when no skill was used).
+  - `tether stats [--model <m>] [--skill <s>] [--limit <n>]` aggregates per-model pass rates, cumulative token economy (`total_prompt_tokens + total_completion_tokens`), step latency, and self-healing ACI friction (`nudge`, `loop_stall`, `cycle_stall`, `syntax_error`, `tool_error`, `gate_fail`, `gate_error`), plus a top-offenders breakdown by tool command.
+- **Post-Mortem Distillation (`tether retro <session_id> [--apply] [--model <m>]`):** offline only (never mutates a live prompt). `store.extract_friction_trace` pulls `inbox` corrections and `loop_stall`/`cycle_stall`/`syntax_error`/`tool_error`/`gate_fail`/`gate_error` turns (+ the fixing command); one bounded LLM pass yields ≤2 rules (≤30 tokens each, deduped against existing rules). Prints a unified diff of `SKILL.md`; `--apply` appends under `## Learned Rules` (or pins to project memory when no skill was used).
 - **Headless Worker & Live `send` Contract:**
   - `tether run --headless ...` creates the session row in SQLite and spawns `python -m tether.cli _worker <session_id>` via `subprocess.Popen(..., start_new_session=True)`, printing `<session_id>` immediately to stdout.
   - Before each step, the running worker queries `inbox WHERE session_id = ? AND consumed = 0` and injects any new user/parent messages into the conversation.
@@ -123,7 +125,7 @@ tether/
   - `agent status <id>` $\rightarrow$ returns 1-line status, step count, and last command.
   - `agent wait <id1> [id2 ...]` $\rightarrow$ asynchronously polls SQLite until the specified child session(s) finish and returns a **compact ~50-token digest** (status, total chars/chunks, 2-line preview) so the parent's context window is never flooded.
   - `agent query <id|--all> <query> [--top 3]` $\rightarrow$ queries `chunks_fts` (BM25 ranking) across the sub-agent's final deliverable and raw observations, returning only the top-K relevant chunks (~200–300 tokens).
-  - `agent read <id> [--full]` $\rightarrow$ reads the child session's digest or full `result`.
+  - `agent read <id> [--full]` $\rightarrow$ reads the child session's digest or full `result`. The CLI `tether read <id>` prints the full result by default (`--full` accepted for parity; `--digest` for the digest).
   - `agent send <id> <message>` $\rightarrow$ queues a message into the child session's inbox (or resumes it if completed).
 - **Deterministic Multi-Stage Pipelines (`tether pipeline <pipeline.yaml> "<goal>"` & `Harness.run_pipeline`):**
   - Each stage runs in its own isolated `SessionRecord` (`parent_id = pipeline_session_id`) with heterogeneous model routing (`stage.model`), stage-level `verify` gates, and strict sandbox monotonicity (`root_sandbox.attenuate(stage.sandbox)`).
@@ -142,7 +144,7 @@ tether/
     - pytest -q
   ---
   ```
-- If `skills/<name>/tools.py` exists, any `@tool`-decorated functions inside it are loaded with the skill and registered into the session's multiplexer when their name is also listed in the skill's `tools:` (otherwise: `unknown command`).
+- If `skills/<name>/tools.py` exists, any `@tool`-decorated functions inside it are loaded with the skill and registered into the session's multiplexer when their name is also listed in the skill's `tools:` (otherwise: `unknown command`). A skill's own custom tools are opt-in like any other, so they must be listed in `tools:`; loading a skill whose `tools.py` defines an unlisted `@tool` emits a `UserWarning` (0 prompt tokens).
 
 #### D. 3 Thin `httpx` Model Providers & SDK Provider Routing (`providers/`)
 - Model identifier format: `<provider>/<model_name>` (e.g., `ollama/qwen3.5:9b`, `openai/gpt-4o-mini`, `anthropic/claude-3-7-sonnet-latest`).
@@ -155,6 +157,8 @@ tether/
   - `ANTHROPIC_API_KEY`, `ANTHROPIC_BASE_URL` (default `https://api.anthropic.com`)
 
 ---
+- **Timeout/retry (#70):** `providers.yaml` `timeout` applies to every kind; HTTP providers retry timeouts/network errors/429/5xx twice (`post_with_retry` in `providers/base.py`) then raise `ProviderError` naming provider, model and timeout.
+- **Context config (#54):** `max_context_tokens` / `fold_observations_after` resolve as explicit argument (`--context-tokens` / `--fold-after`, MCP `context_tokens` / `fold_after`) > `providers.yaml` entry keys `context_tokens` / `fold_after` > defaults 8192 / 2.
 
 ## 4. Development Workflow & Commands
 

{tether_sdk-0.2.1 → tether_sdk-0.2.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: tether-sdk
-Version: 0.2.1
+Version: 0.2.3
 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
@@ -109,7 +109,7 @@ Every Tether execution is a stateful session persisted in `.tether/tether.db` (S
   - If **`WAITING_INPUT` / `COMPLETED` / `IDLE`**: appends the message and automatically spawns a worker to resume the session with its pinned memory and folded context intact.
 
 ### 3. Progressive Skills (`skills/`)
-Skills are portable capability bundles stored in `./skills/<name>/SKILL.md` (or `./skills/<name>.md`) with YAML frontmatter (including optional `verify` gates) and an optional sibling `tools.py`:
+Skills are portable capability bundles stored in `./skills/<name>/SKILL.md` (or `./skills/<name>.md`) with YAML frontmatter (including optional `verify` gates) and an optional sibling `tools.py` (every `@tool` in it must also be listed in `tools:`, otherwise it is unavailable and loading the skill emits a `UserWarning`):
 ```markdown
 ---
 name: researcher

{tether_sdk-0.2.1 → tether_sdk-0.2.3}/README.md

@@ -88,7 +88,7 @@ Every Tether execution is a stateful session persisted in `.tether/tether.db` (S
   - If **`WAITING_INPUT` / `COMPLETED` / `IDLE`**: appends the message and automatically spawns a worker to resume the session with its pinned memory and folded context intact.
 
 ### 3. Progressive Skills (`skills/`)
-Skills are portable capability bundles stored in `./skills/<name>/SKILL.md` (or `./skills/<name>.md`) with YAML frontmatter (including optional `verify` gates) and an optional sibling `tools.py`:
+Skills are portable capability bundles stored in `./skills/<name>/SKILL.md` (or `./skills/<name>.md`) with YAML frontmatter (including optional `verify` gates) and an optional sibling `tools.py` (every `@tool` in it must also be listed in `tools:`, otherwise it is unavailable and loading the skill emits a `UserWarning`):
 ```markdown
 ---
 name: researcher

{tether_sdk-0.2.1 → tether_sdk-0.2.3}/docs/architecture.md

@@ -58,6 +58,7 @@ Tether implements a deterministic three-tier memory hierarchy backed by `.tether
    ```text
    [obs_1 folded: `web fetch https://...` (3,420 chars) | use `mem recall obs_1` or `mem search <query>`]
    ```
+   Exception (#69): the latest read of each of the last 4 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|replace`, or any other bash command naming it: `sed -i`, `tee`, redirects, `python -c`) or re-read. The 2,400-char head+tail elision still applies, and the hard context budget remains #81. The `mem recall` hint is shown only when `mem` is enabled (else "re-run the command").
 3. **Sub-Millisecond SQLite FTS5 BM25 RAG**: Every raw observation and final deliverable is automatically chunked (~150 tokens per paragraph/section) and indexed into an FTS5 virtual table (`chunks_fts`) so the agent (or a parent agent) can retrieve exact passages via `mem search` or `agent query`.
 
 ---
@@ -74,8 +75,8 @@ Local inference engines (`Ollama`, `llama.cpp`, `vLLM`) and cloud providers (`An
 ### Deterministic Loop-Stall Breaker & Pre-`done` Verification Gates
 Small 8B/9B models occasionally fall into a probability trap where they emit the exact same command (`web search "..."` or `bash ...`) twice in a row, or prematurely call `done` while tests or linters are failing:
 
-- **Loop-Stall Breaker:** `Harness.execute_session` tracks the `(cmd, stdin)` signature of the previous step and intercepts consecutive duplicates before executing the tool, returning a `[LOOP DETECTED]` nudge that forces the model to advance.
-- **Pre-`done` Verification Gates:** When configured via `Harness(verify=[...])`, CLI `--verify`, or Skill YAML `verify: [...]`, Tether intercepts `done` and runs each verification command inside the session's `SandboxPolicy`. It consumes **0 static prompt tokens** unless a gate exits non-zero—at which point termination is rejected and a compact `[VERIFICATION GATE FAILED]` observation is injected so the model can self-heal.
+- **Loop-Stall Breaker:** `Harness.execute_session` tracks the `(cmd, stdin)` signature of the previous step and intercepts consecutive duplicates before executing the tool, returning a `[LOOP DETECTED]` nudge that forces the model to advance. A companion cycle detector (`detect_cycle`) catches a 2-command cycle repeated 3 times or a 3-command cycle repeated twice (6 actions, within the last 8), skips the repeated command, nudges with `[CYCLE DETECTED]` naming the commands, and records `cycle_stall`.
+- **Pre-`done` Verification Gates:** When configured via `Harness(verify=[...])`, CLI `--verify`, or Skill YAML `verify: [...]`, Tether intercepts `done` and runs each verification command inside the session's `SandboxPolicy`. It consumes **0 static prompt tokens** unless a gate exits non-zero—at which point termination is rejected and a compact `[VERIFICATION GATE FAILED]` observation is injected so the model can self-heal. A gate that errors rather than fails (sandbox violation, exit 124/126/127) ends the session `FAILED` immediately as `gate_error` instead of consuming retries.
 
 ### Connection Pooling & Thread-Local SQLite WAL Reuse
 - Model providers reuse persistent `httpx.AsyncClient` connection pools across all turns in a session, eliminating repeated TCP/TLS handshakes.

{tether_sdk-0.2.1 → tether_sdk-0.2.3}/docs/reference/agent-interface.md

@@ -15,7 +15,7 @@ Machine-readable surface for calling Tether from another agent. Setup per harnes
 - `failure` is `{"kind": "gate|max_steps|worker_error", "gate": "<cmd>|output-schema|null", "message": "…"}`.
 - Keys are stable; new keys may be added.
 
-`--json` is available on `run`, `pipeline`, `status`, `list`, `read` (also `--digest`, `--steps`), `wait`, `send` and `stats`. With `--headless` it prints `{"v":1,"id":"ses_…"}`.
+`--json` is available on `run`, `pipeline`, `status`, `list`, `read` (also `--digest`, `--steps`, `--full`), `wait`, `send` and `stats`. With `--headless` it prints `{"v":1,"id":"ses_…"}`.
 
 ## Exit codes
 
@@ -24,7 +24,7 @@ Machine-readable surface for calling Tether from another agent. Setup per harnes
 | 0 | completed |
 | 1 | usage error (bad flag, unknown session, invalid pipeline) |
 | 2 | waiting for input (`done --ask`) |
-| 3 | verification gate failed (including `--output-schema`) |
+| 3 | verification gate failed or misconfigured (including `--output-schema`) |
 | 4 | max steps reached |
 | 5 | worker or provider error |
 
@@ -42,7 +42,7 @@ Optional: `pip install "tether-sdk[mcp]"` (installs the official `mcp` SDK; core
 
 | Tool | Arguments |
 |------|-----------|
-| `tether_run` | `goal`, `model`, `skill`, `tools`, `verify[]`, `max_steps`, `sandbox`, `no_network`, `output_schema`, `wait` (default true) |
+| `tether_run` | `goal`, `model`, `skill`, `tools`, `verify[]`, `max_steps`, `context_tokens`, `fold_after`, `sandbox`, `no_network`, `output_schema`, `wait` (default true) |
 | `tether_status` | `id` |
 | `tether_wait` | `ids[]`, `timeout` |
 | `tether_read` | `id`, `mode` = `full` \| `digest` \| `steps` |

{tether_sdk-0.2.1 → tether_sdk-0.2.3}/docs/reference/context-and-store.md

@@ -22,6 +22,7 @@ When the provider sets `structured_history = True` (Ollama, OpenAI-compatible, A
 
 Raw tool outputs stay in the prompt for $K=2$ turns, then fold into a one-line tombstone (see [Built-in Tools](../tutorial/built-in-tools.md#mem-pinned-scratchpad-bm25-observation-recall)). For small models this has consequences ([#27](https://github.com/igormcsouza/tether/issues/27)), seen in the [course-builder example](https://github.com/igormcsouza/tether/tree/main/examples/course):
 
+- **Fix (#69).** Folding exception: the latest read of each of the last 4 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|replace`, or any other bash command naming it: `sed -i`, `tee`, redirects, `python -c`) or re-read. The 2,400-char head+tail elision still applies, and the hard context budget remains #81. The `mem recall` hint is shown only when `mem` is enabled (else "re-run the command"). (`ContextAssembler(mem_enabled=..., workspace_root=...)`, `MAX_LIVE_READS`).
 - **Re-viewing files loops, then invents data.** The model runs `edit view`, the output folds two turns later, it views again, and eventually writes from memory.
 - **What worked: one compact joined view, used right before the write, that ends with the exact next call.** The `course-source <module>` tool returns a module's plan and chosen videos in one output and finishes with `NOW WRITE THIS MODULE: act("edit write part-N.md", ...)`, so the data is still in the prompt when the write happens.
 - **Write long outputs in small pieces.** One big write dropped a whole section. The writer skill writes one `part-N.md` per module with `edit write`, then a `course-build` tool concatenates them into `course.md`.

tether_sdk-0.2.3/docs/reference/multiplexer-and-decorator.md

@@ -0,0 +1,17 @@
+# Multiplexer and Decorator
+
+## `tether.multiplexer`
+
+A command that is not enabled returns a self-healing error (`unknown_cmd`, no exception) listing the enabled tools and how to enable more (`--tools`, SDK `tools=[...]`, skill `tools:`). A known built-in that is merely disabled (`bash`, `web`, `edit`, `mem`, `skill`, `agent`) is reported as disabled, not unknown. The text lives in the error response (history), never in the system prompt prefix.
+
+::: tether.multiplexer
+    options:
+      show_root_heading: false
+      members_order: source
+
+## `tether.decorator`
+
+::: tether.decorator
+    options:
+      show_root_heading: false
+      members_order: source

{tether_sdk-0.2.1 → tether_sdk-0.2.3}/docs/reference/providers.md

@@ -34,32 +34,56 @@ claude-cli:
   reply: result
   usage: {prompt: [usage.input_tokens, usage.cache_creation_input_tokens, usage.cache_read_input_tokens], completion: usage.output_tokens}
   timeout: 180
+  context_tokens: 32000
+  fold_after: 8
 ```
 
 ```bash
 tether run --model claude-cli/sonnet "fix the failing test"
 ```
 
+### Context budget
+
+Every entry, of any kind, may set two optional positive integers: `context_tokens` (the context budget, default 8192) and `fold_after` (how many recent turns keep full observations, default 2). The `--context-tokens` / `--fold-after` flags and the Harness arguments override them.
+
+### Timeout and retry
+
+Every entry may set `timeout` (positive seconds). It applies to the HTTP kinds (`openai`, `ollama`, `anthropic`; defaults 120 / 120 / 180 s) and to `command` (default 300 s). The HTTP providers retry automatically, at most 2 times with 1 s then 2 s backoff, on timeouts, network errors and HTTP 429/500/502/503/504. A 401/403 is never retried: it raises `ProviderError` naming the provider and the credential variable (`openai: HTTP 401: `NVIDIA_API_KEY` is missing or rejected; set it to a valid key`; the value is never printed), and a declared `api_key_env` that is unset or empty fails the session before any request with the same message. Other 4xx responses are never retried. When retries run out the call raises `ProviderError`, so the session fails with a readable `Worker error: ProviderError: openai model `gpt-4o` unavailable after 3 attempts (timeout 120s, last error: ReadTimeout)`. The retry is invisible to the prompt (0 tokens, no prefix change).
+
 ### Kinds
 
 | `kind` | Fields |
 |---|---|
-| `openai` | `base_url`, `api_key_env` |
-| `ollama` | `host` |
-| `anthropic` | `base_url`, `api_key_env` |
+| `openai` | `base_url`, `api_key_env`, optional `timeout` |
+| `ollama` | `host`, optional `timeout` |
+| `anthropic` | `base_url`, `api_key_env`, optional `timeout` |
 | `command` | `argv` (list), `reply` (JSON path), optional `stdin` template, optional `usage`, optional `timeout` (seconds, default 300) |
 
-`api_key_env` is the **name** of an environment variable, never the key itself.
+`api_key_env` is the **name** of an environment variable, never the key itself. A declared `api_key_env` must be set and non-empty (otherwise the session fails before any request); omit it to declare a keyless local server. A 403 reads `access denied (HTTP 403)` with the first 120 characters of the response body instead of "missing or rejected".
 
 ### The `command` kind
 
 A `command` entry wraps any program that takes a prompt and prints JSON.
 
-- **Placeholders**: `{model}`, `{system}` and `{conversation}` are substituted in `argv` items and in the `stdin` template. If `stdin` is omitted it defaults to `{conversation}`.
+- **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.
 - **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.
-- **Protocol**: the model must answer with a single JSON `{"cmd", "stdin"}` object. The `{system}` placeholder already contains that instruction.
+- **Constrained output**: use `{schema}` to make the CLI constrain its reply to the act schema, for example `argv: [claude, -p, --json-schema, "{schema}", --output-format, json]`. The reply may then be an object with `cmd` and optional `stdin` instead of a string; if the `reply` path gives no string or object, a top-level `structured_output` object is used.
+
+  Measured cost (v0.2.2, one small task): with `claude -p`, `--json-schema` adds about 2k prompt tokens to every call (the CLI wraps the schema in a hidden tool), so the same 5-step task used ~26k prompt tokens instead of ~7k. Use it when a model's plain replies are not being understood, not as a default.
+- **Protocol**: the model should answer with a single JSON `{"cmd", "stdin"}` object. The `{system}` placeholder already contains that instruction.
+- **Dialects**: when the reply is not that JSON, Tether tries table-driven extractors in order, first match wins: `<tool_call>` JSON, raw JSON containing `"cmd"`, `<parameter name="cmd">X</parameter>` with optional `<parameter name="stdin">Y</parameter>` (inside any wrapper such as `<invoke>`), and text `act(...)`.
+- **`dialects:`** (optional): a list of mappings, each with a `regex` (compiled with `re.DOTALL`) that defines the named group `cmd` and optionally `stdin`. Custom dialects are tried after the built-in ones. Python users can also call `tether.register_dialect(fn)` with a `(str) -> ActionCall | None` function.
+
+```yaml
+mycli:
+  kind: command
+  argv: [mycli, "{conversation}"]
+  reply: result
+  dialects:
+    - regex: 'RUN\[(?P<cmd>.*?)\]WITH\[(?P<stdin>.*?)\]'
+```
 
 ### Rules
 

{tether_sdk-0.2.1 → tether_sdk-0.2.3}/docs/release-notes.md

@@ -1,5 +1,37 @@
 # Release Notes
 
+## v0.2.3 (2026-10-20)
+
+Dogfooding fixes: the issues came from running Tether with a small model (GLM-5.3) on its own backlog.
+
+### Features
+
+- `tether read` now accepts `--full` (the full final result, already its default) so the `agent read <id> --full` form works on the CLI too; `--digest` still gives the compact card (#72).
+
+### Fixes
+
+- Verification gate errors (sandbox violation, exit 124/126/127) are now told apart from gate failures: the session fails immediately with a `Verification gate ... misconfigured: <reason>` result (exit code 3) instead of burning the 3-failure abort budget, and `tether stats` shows a `GATE_ERR` column (#33).
+- `edit write` over an existing file now returns a deterministic summary (`Replaced N lines with M (X removed, Y added; first removed: ...)`) and, when the file shrank, points to `edit replace --lines a:b` (#40).
+- Skills now warn (`UserWarning`, 0 prompt tokens) at load when `tools.py` defines a `@tool` not listed in the skill `tools:` (#24).
+- Repeated multi-command cycles (e.g. `cat` / `sed` / `pytest`, or two alternating `sed -n` ranges) now trigger a deterministic `[CYCLE DETECTED]` nudge and a new `cycle_stall` event type, shown in `tether stats` as `CYCLES` (#39).
+- HTTP providers now retry timeouts, network errors and 429/5xx twice with backoff, honour `timeout` from `providers.yaml` for all kinds, and fail with a `ProviderError` naming provider, model and timeout instead of a bare `ReadTimeout` (#70).
+- Observation folding no longer makes small models re-read files in a loop: the latest read (`edit view <p>` / `bash cat|head|tail|sed -n <p>`) of each of the last 4 files stays unfolded until that path is edited (`edit write|replace`, or a bash write such as `sed -i`/`tee`) or re-read, and the fold/elision hint only mentions `mem recall` when `mem` is enabled (otherwise "re-run the command"). Static prompt prefix unchanged (#69).
+- Clearer errors (#71): a provider 401/403 now fails with `ProviderError` naming the provider and the `api_key_env` / default key variable as missing or rejected (never its value), a declared `api_key_env` that is empty fails before the first request, and `unknown command` for a built-in tool that is not enabled says it is disabled and how to enable it (`--tools`, `tools=[...]`, skill `tools:`). Static prompt prefix unchanged.
+
+## v0.2.2 (2026-10-19)
+
+Dogfooding fixes: Tether implemented most of this release itself through the CLI and a `claude -p` provider.
+
+### Features
+
+- `{schema}` placeholder for `command` providers (#51): constrain output to the act schema (e.g. `claude -p --json-schema '{schema}'`); replies may be structured objects with `cmd`/`stdin`.
+- `tether misses [session_id] [--model M] [--limit N] [--json]` (#53): list unparsed model replies (nudges) as fixture-ready JSONL; paste lines into `tests/fixtures/dialects.jsonl` after filling `expected`.
+
+### Fixes
+
+- The context budget and observation fold window are now configurable (#54): `--context-tokens` / `--fold-after` on `tether run` and `tether pipeline`, `context_tokens` / `fold_after` on `tether_run`, and per-provider keys in `providers.yaml`.
+- Tool-call dialect extraction is now table-driven (#52): built-in extractors for `<tool_call>` JSON, raw JSON, `<parameter name="cmd">` blocks and text `act(...)`, extendable with `tether.register_dialect` or a `dialects:` key on `command` entries in `providers.yaml`.
+
 ## v0.2.1 (2026-10-19)
 
 Add model backends without code.

{tether_sdk-0.2.1 → tether_sdk-0.2.3}/docs/troubleshooting.md

@@ -6,15 +6,18 @@ Symptom, cause, fix. Most entries come from building the [course-builder example
 |---|---|---|
 | Model keeps running `edit view` on the same file, then writes invented data | Old observations fold after 2 turns ([#27](https://github.com/igormcsouza/tether/issues/27)) | Give it one compact tool view right before the write, ending with the exact next call. See [Context and SQLite Store](reference/context-and-store.md#observation-folding-and-small-models) |
 | A long `edit write` is missing a whole section | One big generation drops content | Write one small file per section (`part-N.md`) and join them with a tool. [Same page](reference/context-and-store.md#observation-folding-and-small-models) |
-| Earlier file content vanished after a second `edit write` | `edit write` replaces the whole file ([#34](https://github.com/igormcsouza/tether/issues/34)) | Tell the model to rewrite the complete file, or use `edit replace --lines`. See [Built-in Tools](tutorial/built-in-tools.md#example-course-builder) |
+| Earlier file content vanished after a second `edit write` | `edit write` replaces the whole file ([#34](https://github.com/igormcsouza/tether/issues/34)) | `edit write` now reports what an overwrite removed (#40). Tell the model to rewrite the complete file, or use `edit replace --lines`. See [Built-in Tools](tutorial/built-in-tools.md#example-course-builder) |
 | Files contain a literal `\n` | Model sent escaped newlines in stdin | Fixed in v0.1.2 for `edit write`, `edit replace` and `done` |
 | Tool with multi-word argument fails (`unexpected keyword argument`, wrong value) | Unquoted words were not joined | Fixed in v0.1.2. See [argument parsing](tutorial/sdk-and-custom-tools.md#argument-parsing-v012) |
-| `Error: unknown command` for a tool defined in `tools.py` | The tool is not in the skill `tools:` list ([#24](https://github.com/igormcsouza/tether/issues/24)) | Add its name to `tools:`. See [Skills](tutorial/skills.md#tools-py-and-the-tools-list) |
+| `Error: unknown command` for a tool defined in `tools.py` | The tool is not in the skill `tools:` list ([#24](https://github.com/igormcsouza/tether/issues/24)) | Add its name to `tools:` (loading the skill emits a `UserWarning` naming unlisted tools). See [Skills](tutorial/skills.md#tools-py-and-the-tools-list) |
+| `Worker error: ProviderError: ... `NVIDIA_API_KEY` is missing or rejected` | The provider answered 401/403, or the `api_key_env` variable is unset/empty ([#71](https://github.com/igormcsouza/tether/issues/71)) | Export a valid key under that variable name (Tether prints the name, never the value). An empty `api_key_env` variable fails the session before any request |
+| `Error: \`bash\` is disabled` / `unknown command` | The tool is not enabled for this session; the message lists the enabled tools | Add it with `--tools bash,edit`, SDK `tools=[...]` or the skill `tools:` list ([#71](https://github.com/igormcsouza/tether/issues/71)) |
+| Model answers are not understood (many nudges in `tether stats`) | The reply format is not parsed into an action | Run `tether misses`, then add a dialect: paste the lines into `tests/fixtures/dialects.jsonl` or add a `dialects:` regex to `providers.yaml` |
 | Gate with inline `awk`/`sed` is blocked as "absolute path outside workspace" | Fixed in v0.1.4 ([#31](https://github.com/igormcsouza/tether/issues/31)); older versions saw a program starting with `/` as a path | Upgrade, or move the logic into a script (`python3 checks.py ...`). See [Security and Sandbox](tutorial/security-and-sandbox.md#example-awksed-programs-that-start-with) |
 | `Ollama model … not found; installed: …` | The model name is not pulled; Tether no longer substitutes another one ([#21](https://github.com/igormcsouza/tether/issues/21)) | `ollama pull <model>`, fix the name, or set `TETHER_OLLAMA_FALLBACK=1` to opt in to a substitute |
 | `tether mcp` prints "MCP support is not installed" | The optional extra is missing | `pip install "tether-sdk[mcp]"`. See [Use Tether Inside Your Harness](tutorial/agent-interface.md) |
 | Gate exits 0 although work is missing | Missing input file means nothing to check | Make the gate fail closed. See [Gates](tutorial/workflows-and-telemetry.md#gates) |
-| Session `FAILED` after 3 gate failures, none of them real | A gate environment error counts as a failure ([#33](https://github.com/igormcsouza/tether/issues/33)) | Run the gate command by hand first |
+| Session `FAILED` with `Verification gate ... misconfigured` | The gate itself errored (sandbox violation, command not found, timeout), not your work; it fails fast and shows as `gate_error` in `tether stats` | Fix the gate command and run it by hand first |
 | Model repeats a tool call with a rejected value | Gate or tool message says what failed, not what to do | Return the valid options and the next call in the message. See [Custom Tools](tutorial/sdk-and-custom-tools.md#example-course-builder) |
 | A pipe-delimited file gets extra or shifted columns | A delimiter (` | `) appeared inside a value | Sanitize values in the tool that writes the file |
 | Pipeline stage ends "Max steps reached" | `max_steps` too small for the work ([#35](https://github.com/igormcsouza/tether/issues/35)) | Raise `max_steps` (pipeline or stage), or re-run the stage's skill by hand. See [Pipelines](tutorial/workflows-and-telemetry.md#pipelines) |
@@ -22,7 +25,7 @@ Symptom, cause, fix. Most entries come from building the [course-builder example
 
 ## Known limitations
 
-- [#24](https://github.com/igormcsouza/tether/issues/24) skill `tools.py` tools must also be listed in `tools:`.
+- [#24](https://github.com/igormcsouza/tether/issues/24) skill `tools.py` tools must also be listed in `tools:` (a `UserWarning` is emitted at load otherwise).
 - [#27](https://github.com/igormcsouza/tether/issues/27) observation folding hurts small models.
 - [#32](https://github.com/igormcsouza/tether/issues/32) model reasoning is not in the trace.
 - [#33](https://github.com/igormcsouza/tether/issues/33) gate infrastructure errors count toward the 3-failure abort.

{tether_sdk-0.2.1 → tether_sdk-0.2.3}/docs/tutorial/built-in-tools.md

@@ -82,7 +82,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.** Small models assume it appends and silently lose earlier content. The planner skill says so explicitly: "write the COMPLETE plan in ONE call". (An `edit append` is proposed in [#34](https://github.com/igormcsouza/tether/issues/34).)
+- **`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. The planner skill says so explicitly: "write the COMPLETE plan in ONE call". (An `edit append` is proposed in [#34](https://github.com/igormcsouza/tether/issues/34).)
 - **`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.2.1 → tether_sdk-0.2.3}/docs/tutorial/cli-and-headless.md

@@ -63,9 +63,12 @@ tether status "$SESSION_ID"
 # Block until the session completes and print a compact ~50-token digest
 tether wait "$SESSION_ID"
 
-# Read the full final deliverable
+# Read the full final deliverable (`--full` is optional: it is the default)
 tether read "$SESSION_ID"
 
+# Or just the compact digest
+tether read "$SESSION_ID" --digest
+
 # Inspect the step-by-step action log
 tether read "$SESSION_ID" --steps
 
@@ -76,10 +79,22 @@ tether query "$SESSION_ID" "write-ahead log checkpointing" --top 3
 tether list
 ```
 
+## Context budget and fold window
+
+By default Tether keeps an 8192-token context budget and folds observations older than 2 turns. Tune both per run with `--context-tokens N` and `--fold-after N` (on `tether run` and `tether pipeline`), or per model in `providers.yaml` with `context_tokens` / `fold_after`. Flags override the provider entry, which overrides the defaults.
+
+```bash
+tether run --context-tokens 32000 --fold-after 8 "refactor the parser"
+```
+
 ## Scripting: `--json` and exit codes
 
 `run`, `pipeline`, `status`, `list`, `read`, `wait`, `send` and `stats` accept `--json`. Exit codes: `0` completed, `1` usage error, `2` waiting for input, `3` gate failed, `4` max steps, `5` worker error. A failure reason goes to stderr, never stdout. `--result-file <path>` writes the deliverable to a file, `--output-schema <schema.json>` rejects a `done` whose JSON does not match, and `tether events <id> --follow` streams turns as JSONL. Details: [Agent Interface reference](../reference/agent-interface.md).
 
+### When a model's replies are not understood
+
+If a model keeps answering in a format Tether cannot parse into an action (many nudges in `tether stats`), run `tether misses [session_id] [--model M] [--limit N] [--json]`. It lists the unparsed replies; with `--json` each line is fixture-ready. Paste lines into `tests/fixtures/dialects.jsonl` after filling `expected`, or add a `dialects:` regex to `providers.yaml`.
+
 ## Live Inbox Injection & Auto-Resume (`tether send`)
 
 Every session has a persistent SQLite `inbox` queue:

{tether_sdk-0.2.1 → tether_sdk-0.2.3}/docs/tutorial/skills.md

@@ -91,7 +91,7 @@ verify:
 
 ### <a id="tools-py-and-the-tools-list"></a>`tools.py` and the `tools:` list
 
-Defining a tool in `tools.py` is not enough: name it in the skill `tools:` as well, or the model gets `unknown command` ([#24](https://github.com/igormcsouza/tether/issues/24)). See [Python SDK and Custom Tools](sdk-and-custom-tools.md).
+Defining a tool in `tools.py` is not enough: name it in the skill `tools:` as well, or the model gets `unknown command` ([#24](https://github.com/igormcsouza/tether/issues/24)). A skill's own custom tools are opt-in like built-in ones, so list them in `tools:`. Loading a skill whose `tools.py` defines an unlisted `@tool` emits a `UserWarning` naming it (costs no prompt tokens). See [Python SDK and Custom Tools](sdk-and-custom-tools.md).
 
 ### Let the model decide, let code enforce hard requirements
 

{tether_sdk-0.2.1 → tether_sdk-0.2.3}/docs/tutorial/workflows-and-telemetry.md

@@ -10,7 +10,7 @@ A gate is a shell command that must exit `0` before `done` can complete the sess
 tether run --tools bash,edit --verify "pytest -q" --verify "ruff check ." "Fix the failing test"
 ```
 
-If a gate fails, `done` is rejected and a `[VERIFICATION GATE FAILED: ...]` observation is injected so the model can fix the problem and retry. After repeated consecutive failures the session ends `FAILED`. Gates can also come from `Harness(verify=[...])` or a Skill's `verify:` frontmatter list.
+If a gate fails, `done` is rejected and a `[VERIFICATION GATE FAILED: ...]` observation is injected so the model can fix the problem and retry. After repeated consecutive failures the session ends `FAILED`. A gate that is itself broken (sandbox violation, command not found, exit 126/127, timeout) is not retried: the session ends `FAILED` immediately with a `Verification gate ... misconfigured: <reason>` result, the turn is recorded as `gate_error`, and the exit code is still `3`. Gates can also come from `Harness(verify=[...])` or a Skill's `verify:` frontmatter list.
 
 ## Asking for input (`done --ask`)
 
@@ -70,7 +70,7 @@ Each stage needs a `goal`. Invalid manifests print `Error: invalid pipeline ...`
 tether stats [--model <m>] [--skill <s>] [--limit <n>]
 ```
 
-Prints per-model runs, pass rate, average steps, peak and total tokens, and friction counts (`nudge`, `loop_stall`, `syntax_error`, `tool_error`, `gate_fail`), followed by the commands that cause the most friction. Pipeline root sessions are excluded so tokens are not double-counted.
+Prints per-model runs, pass rate, average steps, peak and total tokens, and friction counts (`nudge`, `loop_stall`, `cycle_stall`, `syntax_error`, `tool_error`, `gate_fail`, `gate_error`), followed by the commands that cause the most friction. Pipeline root sessions are excluded so tokens are not double-counted.
 
 ## Post-mortem rules (`tether retro`)
 
@@ -126,4 +126,4 @@ sqlite3 .tether/tether.db \
   "select step, event_type, tool_cmd from turns where session_id='$SID' and tool_cmd is not null order by step"
 ```
 
-`turns.event_type` is one of `ok`, `nudge`, `loop_stall`, `syntax_error`, `tool_error`, `gate_fail`, `completed`; the non-`ok` ones are what `tether stats` counts as friction. Model **reasoning is not recorded** (only the action and its output), so a "thinking" model that loops shows no visible cause ([#32](https://github.com/igormcsouza/tether/issues/32)).
+`turns.event_type` is one of `ok`, `nudge`, `loop_stall`, `cycle_stall`, `syntax_error`, `tool_error`, `gate_fail`, `gate_error`, `completed`; the non-`ok` ones are what `tether stats` counts as friction. Model **reasoning is not recorded** (only the action and its output), so a "thinking" model that loops shows no visible cause ([#32](https://github.com/igormcsouza/tether/issues/32)).

tether_sdk-0.2.3/tests/fixtures/dialects.jsonl

@@ -0,0 +1,6 @@
+{"reply": "<tool_call>{\"name\": \"act\", \"arguments\": {\"cmd\": \"ls -la\"}}</tool_call>", "cmd": "ls -la", "stdin": null}
+{"reply": "Sure: {\"cmd\": \"echo hi\"}", "cmd": "echo hi", "stdin": null}
+{"reply": "act(\"done\", stdin=\"x\")", "cmd": "done", "stdin": "x"}
+{"reply": "<invoke name=\"act\">\n<parameter name=\"cmd\">  pytest -q  </parameter>\n</invoke>", "cmd": "pytest -q", "stdin": null}
+{"reply": "<invoke name=\"act\">\n<parameter name=\"cmd\">edit write a.txt</parameter>\n<parameter name=\"stdin\">line1\nline2\n</parameter>\n</invoke>", "cmd": "edit write a.txt", "stdin": "line1\nline2\n"}
+{"reply": "I will think about this and answer in plain prose.", "cmd": null, "stdin": null}

{tether_sdk-0.2.1 → tether_sdk-0.2.3}/tests/providers/test_anthropic.py

@@ -5,8 +5,10 @@ from __future__ import annotations
 import json
 
 import httpx
+import pytest
 
 from tether.providers.anthropic import AnthropicProvider
+from tether.providers.base import ProviderError
 
 
 async def test_anthropic_provider_and_ephemeral_cache() -> None:
@@ -60,3 +62,13 @@ async def test_anthropic_provider_and_ephemeral_cache() -> None:
     c_anth_new = anth._get_client()
     assert not c_anth_new.is_closed
     await anth.aclose()
+
+
+async def test_anthropic_401_names_env_var(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setenv("ANTHROPIC_API_KEY", "sk-SECRET")
+    prov = AnthropicProvider("m")
+    prov._client = httpx.AsyncClient(transport=httpx.MockTransport(lambda r: httpx.Response(401)))
+    with pytest.raises(ProviderError) as ei:
+        await prov.generate([{"role": "user", "content": "x"}], [])
+    assert "`ANTHROPIC_API_KEY` is missing or rejected" in str(ei.value)
+    assert "sk-SECRET" not in str(ei.value)

{tether_sdk-0.2.1 → tether_sdk-0.2.3}/tests/providers/test_declarative.py

@@ -5,6 +5,7 @@ import json
 import sys
 from pathlib import Path
 
+import httpx
 import pytest
 
 from tether.providers import (
@@ -13,8 +14,9 @@ from tether.providers import (
     OpenAIProvider,
     resolve_provider,
 )
-from tether.providers.base import ModelResponse
+from tether.providers.base import ModelResponse, ProviderError
 from tether.providers.declarative import (
+    ACT_SCHEMA,
     CommandProvider,
     build_declared,
     load_declared,
@@ -95,6 +97,25 @@ def test_build_openai_with_api_key_env(monkeypatch: pytest.MonkeyPatch) -> None:
     assert provider.base_url.startswith("http://x/v1")
 
 
+def test_build_declared_empty_key_env_fails_early(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setenv("MY_KEY", "")
+    with pytest.raises(ProviderError, match="`MY_KEY` is missing or rejected"):
+        build_declared({"kind": "openai", "api_key_env": "MY_KEY"}, "m", num_ctx=1024)
+    monkeypatch.delenv("MY_KEY")
+    with pytest.raises(ProviderError, match="`MY_KEY`"):
+        build_declared({"kind": "anthropic", "api_key_env": "MY_KEY"}, "m", num_ctx=1024)
+
+
+async def test_declared_401_names_env_var(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setenv("MY_KEY", "sk-SECRET")
+    prov = build_declared({"kind": "openai", "api_key_env": "MY_KEY"}, "m", num_ctx=1024)
+    assert isinstance(prov, OpenAIProvider)
+    prov._client = httpx.AsyncClient(transport=httpx.MockTransport(lambda r: httpx.Response(401)))
+    with pytest.raises(ProviderError) as ei:
+        await prov.generate([{"role": "user", "content": "x"}], [])
+    assert "`MY_KEY` is missing or rejected" in str(ei.value) and "sk-SECRET" not in str(ei.value)
+
+
 def test_build_ollama(monkeypatch: pytest.MonkeyPatch) -> None:
     cfg = {"kind": "ollama", "host": "http://h:11434"}
     provider = build_declared(cfg, "m", num_ctx=1024)
@@ -300,3 +321,100 @@ def test_command_validation_errors(
     _write(monkeypatch, tmp_path, f"cli:\n  kind: command\n  {body}")
     with pytest.raises(ValueError, match=f"providers.yaml: entry `cli`.*{message}"):
         load_declared()
+
+
+def test_command_custom_dialect_end_to_end() -> None:
+    from tether.providers.declarative import _build_dialects
+
+    text = "RUN[ls -la]WITH[body]"
+    code = f"import json; print(json.dumps({{'r': {text!r}}}))"
+    dialects = _build_dialects([{"regex": r"RUN\[(?P<cmd>.*?)\]WITH\[(?P<stdin>.*?)\]"}])
+    resp = _run(CommandProvider("m", argv=_script(code), reply="r", dialects=dialects))
+    assert resp.action is not None
+    assert resp.action.cmd == "ls -la"
+    assert resp.action.stdin == "body"
+
+
+def test_command_custom_dialect_no_match_and_empty_cmd() -> None:
+    from tether.providers.declarative import _build_dialects
+
+    dialects = _build_dialects([{"regex": r"RUN\[(?P<cmd>.*?)\]"}])
+    assert dialects[0]("nothing here") is None
+    assert dialects[0]("RUN[   ]") is None
+    call = dialects[0]("RUN[ pwd ]")
+    assert call is not None
+    assert call.cmd == "pwd"
+    assert call.stdin is None
+
+
+@pytest.mark.parametrize(
+    ("dialects", "message"),
+    [
+        ("dialects: nope", "invalid `dialects`"),
+        ("dialects: [1]", "`regex` required"),
+        ("dialects: [{foo: bar}]", "`regex` required"),
+        ("dialects: [{regex: '('}]", "invalid `dialects` regex"),
+        ("dialects: [{regex: 'abc'}]", "named group `cmd`"),
+    ],
+)
+def test_command_dialects_validation_errors(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: Path, dialects: str, message: str
+) -> None:
+    _write(
+        monkeypatch,
+        tmp_path,
+        f"cli:\n  kind: command\n  argv: [echo]\n  reply: r\n  {dialects}\n",
+    )
+    with pytest.raises(ValueError, match=f"providers.yaml: entry `cli`.*{message}"):
+        load_declared()
+
+
+_SCHEMA = json.dumps(ACT_SCHEMA, separators=(",", ":"))
+
+
+def test_schema_placeholder_in_argv_and_stdin() -> None:
+    code = (
+        "import sys,json;"
+        "s = sys.argv[1] + '|' + sys.stdin.read();"
+        "print(json.dumps({'r': json.dumps({'cmd': 'a', 'stdin': s})}))"
+    )
+    provider = CommandProvider("m", argv=_script(code, "{schema}"), reply="r", stdin="in:{schema}")
+    resp = _run(provider)
+    assert resp.action is not None
+    assert resp.action.stdin == f"{_SCHEMA}|in:{_SCHEMA}"
+
+
+def test_reply_dict_with_cmd_and_stdin() -> None:
+    code = "import json;print(json.dumps({'r': {'cmd': 'ls', 'stdin': 'x'}}))"
+    resp = _run(CommandProvider("m", argv=_script(code), reply="r"))
+    assert resp.action is not None
+    assert (resp.action.cmd, resp.action.stdin) == ("ls", "x")
+    assert json.loads(resp.content) == {"cmd": "ls", "stdin": "x"}
+
+
+def test_reply_dict_with_cmd_no_stdin() -> None:
+    code = "import json;print(json.dumps({'r': {'cmd': 'ls', 'stdin': None}}))"
+    resp = _run(CommandProvider("m", argv=_script(code), reply="r"))
+    assert resp.action is not None
+    assert resp.action.stdin is None
+
+
+def test_structured_output_fallback() -> None:
+    code = "import json;print(json.dumps({'result': '', 'structured_output': {'cmd': 'pwd'}}))"
+    resp = _run(CommandProvider("m", argv=_script(code), reply="missing"))
+    assert resp.action is not None
+    assert resp.action.cmd == "pwd"
+
+
+def test_reply_dict_without_cmd_falls_back() -> None:
+    code = "import json;print(json.dumps({'r': {'foo': 1}}))"
+    resp = _run(CommandProvider("m", argv=_script(code), reply="r"))
+    assert resp.content == ""
+    assert resp.action is None
+
+
+def test_reply_string_still_works() -> None:
+    code = "import json;print(json.dumps({'r': json.dumps({'cmd': 'ls'})}))"
+    resp = _run(CommandProvider("m", argv=_script(code), reply="r"))
+    assert resp.action is not None
+    assert resp.action.cmd == "ls"