turnloop 0.1.2__tar.gz → 0.1.4__tar.gz

{turnloop-0.1.2 → turnloop-0.1.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: turnloop
-Version: 0.1.2
+Version: 0.1.4
 Summary: A local-first agentic coding harness: streaming tool loop, permission gating, context compaction, subagents, and any LLM provider.
 Project-URL: Homepage, https://github.com/Pranesh-2005/turnloop
 Author: Pranesh
@@ -49,7 +49,7 @@ tl experiment run smoke         # a measurement run, offline and free
 
 Four runtime dependencies: `textual`, `pydantic`, `httpx`, `pyyaml`. No vendor
 SDKs, no agent framework — the loop is the point, so the loop is written here.
-~18,000 lines of Python, 249 tests, no network in the default test run.
+~18,000 lines of Python, 255 tests, no network in the default test run.
 
 ---
 
@@ -117,7 +117,7 @@ point.
 Verify:
 
 ```bash
-tl --version                # turnloop 0.1.0
+tl --version                # turnloop 0.1.4
 tl doctor                   # every provider, key presence, shell, context budget
 ```
 
@@ -126,7 +126,7 @@ tl doctor                   # every provider, key presence, shell, context budge
 context arithmetic for the active provider:
 
 ```
- + context budget     32,000 window − 4,096 output − 835 system − 3,365 tools = 23,704 for history
+ + context budget     32,000 window - 4,096 output - 881 system - 3,567 tools = 23,456 for history
 ```
 
 ---
@@ -143,8 +143,14 @@ tl --resume                                 # resume the most recent session
 tl --resume <session-id>                    # resume a specific one
 tl sessions                                 # list recorded sessions
 tl config                                   # merged config + which layer each value came from
+tl config --edit                            # interactive settings editor
+tl mcp                                      # add, edit, enable/disable, remove MCP servers
 ```
 
+`config --edit` and `mcp` are deliberately the only paths that write a settings file,
+and neither is reachable by the model — see
+[Editing configuration](#editing-configuration).
+
 ### Flags
 
 | flag | meaning |
@@ -195,9 +201,10 @@ focus and would otherwise swallow them.
 /compact     summarize conversation now /memory       discovered memory files
 /cost        token and cost accounting  /tools        available tools
 /context     what is filling the window /mcp          MCP server status
-/model       show or change model       /hooks        configured hooks
-/provider    switch provider            /sessions     recorded sessions
-/export      transcript to markdown     /doctor       diagnostics
+/model       show or change model       /mcp add      add an MCP server
+/provider    switch provider            /config       settings editor
+/export      transcript to markdown     /hooks        configured hooks
+/sessions    recorded sessions          /doctor       diagnostics
 /quit        exit
 ```
 
@@ -336,7 +343,18 @@ every segment is allowed.** Without that, `Bash(git *)` grants
 scanner that respects quoting — `shlex` discards operators, so the `rm` comes back
 looking like an argument to `git`. 48 tests cover this file alone.
 
-Ten deny rules ship by default, including `Read(**/.env)`.
+Twelve deny rules ship by default, including `Read(**/.env)` and — since 0.1.4 —
+`Write(**/.turnloop/settings*.json)` and `Edit(**/.turnloop/settings*.json)`. Those two
+close a self-escalation path: settings files set `permission_mode` and
+`permissions.allow`, so a model that could write one could grant itself `bypass` on the
+next launch. Verified against the real engine *in bypass mode*, which is the case that
+matters — deny beats bypass, so the block holds even there.
+
+It is a guardrail, not a sandbox, and the boundary is worth being precise about. `Write`
+and `Edit` are blocked; **`Bash` is not**, so a shell redirect reaches the same file.
+Closing that properly needs a path guard below the tool layer rather than more patterns.
+In `default` mode Bash asks a human first, so this only bites under `bypass` — which is
+already the mode that means "I accept the consequences."
 
 ### Context compaction
 
@@ -429,6 +447,12 @@ new users`. `gemini-flash-latest` follows Google's own pointer. Worth knowing wh
 reading a 429 from any provider: the status code says "slow down", the body says
 whether slowing down will ever help.
 
+Its free tier is **5 requests per minute**, which an agent loop reaches in one
+ordinary task — a fix-two-bugs-and-write-tests run spent six turns and died on the
+seventh. The retry ladder is correct and still loses, because the window is longer
+than the backoff. Free Gemini is a good way to try the harness and a bad way to do
+sustained work.
+
 ---
 
 ## Adding a provider
@@ -825,10 +849,31 @@ suddenly have them exposed.
 never manifested only because `rg` was not installed on the machine and it had been
 falling back to a pure-Python walk.
 
-**The lesson, three times over in one project:** an 84-run sweep failing while
-printing a tidy report of zeros; a tool returning empty with `ok: true`; a sweep
-sitting at 10/18 doing nothing for 25 minutes. Each was caught only by looking past
-the summary line.
+**The Gemini adapter passed a live test and was still broken.**
+
+Gemini returns a `thoughtSignature` alongside each `functionCall` part. Replay the
+assistant turn without it and the next request is rejected: `400 — Function call is
+missing a thought_signature in functionCall parts`. The adapter decoded the call and
+dropped the signature, so **turn two of every tool conversation failed**.
+
+It was verified live before shipping — one text turn, one tool call, both correct —
+and that verification is exactly what hid the bug. A single tool call never replays
+anything. The failure needs a *second* request carrying the first one's output, which
+is the first thing a real agent loop does and the last thing a smoke test does.
+
+Found by setting the harness up as a user would and giving it an ordinary task, not by
+testing the adapter. The signature now round-trips through `ToolUseBlock.signature`
+and through session JSONL, so a `--resume`d conversation does not hit the same wall.
+
+**0.1.2 shipped with this bug.** It went to PyPI on the strength of the single-turn
+check, and anyone who pointed 0.1.2 at Gemini got one working tool call and then a
+400. Fixed in 0.1.3.
+
+**The lesson, four times over in one project:** an 84-run sweep failing while printing
+a tidy report of zeros; a tool returning empty with `ok: true`; a sweep sitting at
+10/18 doing nothing for 25 minutes; an adapter passing its live test and failing on
+the turn the test never made. Each was caught only by looking past the summary line —
+and the last one only by using the thing instead of testing it.
 
 ---
 
@@ -862,7 +907,7 @@ one-line edit in a CRLF checkout does not produce a whole-file diff.
 ## Testing
 
 ```bash
-pytest                    # 249 tests, no network
+pytest                    # 283 tests, no network
 ruff check turnloop
 mypy turnloop
 ```
@@ -871,13 +916,15 @@ mypy turnloop
 |---|---|---|
 | `test_permissions.py` | 48 | rule grammar, compound-command splitting, mode enforcement |
 | `test_experiments.py` | 36 | runner, graders, report, suite invariants, config resolution |
-| `test_providers.py` | 31 | adapters against recorded `.sse` fixtures, image block encoding |
+| `test_providers.py` | 35 | adapters vs recorded `.sse`, image blocks, thought signatures |
 | `test_tools_files.py` | 28 | Read/Write/Edit/Glob/Grep, encodings, newlines, image detection |
 | `test_loop.py` | 20 | streaming, truncation, iteration cap |
-| `test_hooks_mcp_commands.py` | 20 | lifecycle hooks, MCP client, slash commands |
-| `test_config.py` | 19 | layering, env overrides, capability presets |
+| `test_hooks_mcp_commands.py` | 23 | lifecycle hooks, MCP client, slash commands |
+| `test_config.py` | 21 | layering, env overrides, presets, narrow-console guard |
 | `test_compaction.py` | 16 | three tiers, tool_use/tool_result invariant |
 | `test_bash.py` | 14 | shell selection, process-tree kill |
+| `test_configio.py` | 15 | minimal-diff writes, atomic save, secret-bearing MCP targets, the settings deny rules |
+| `test_config_screen.py` | 10 | provider form validation, caps derivation, env indicator leaks |
 | `test_websearch.py` | 9 | HTML parsing, backend selection, truncation, failure modes |
 | `test_tui.py` | 8 | Textual snapshots |
 
@@ -930,6 +977,87 @@ Shell expansion inside a command template (`` !`cmd` ``) goes through the permis
 engine like any other Bash call. A markdown file in a repository is not trusted input
 just because it is on disk.
 
+### Editing configuration
+
+`tl config --edit` edits the provider table, permission mode, tool verbosity, iteration
+cap, search backend, memory, and the three rule lists. `tl mcp` manages MCP servers. The
+same screens open inside a running session as `/config` and `/mcp add`.
+
+**Adding a provider** is a form for `kind`, `model`, `base_url`, and `api_key_env`, with
+a live ✓/✗ showing whether that environment variable is currently set. Capabilities are
+re-derived from `preset_for(model)` on every save, mirroring what `load_settings` does
+for `--model` — without that, a provider added through the UI keeps the previous model's
+context window and pricing, and `doctor`'s context-budget line quietly lies. An
+`openai_compat` provider without a `base_url` is refused by the form, because
+`load_settings` would otherwise raise on the *next* launch, turning a typo into a CLI
+that will not start.
+
+Four further properties are structural rather than cosmetic:
+
+**Only the diff is written.** Neither screen dumps the settings model. It writes the
+difference against the packaged defaults, merged into whatever the file already holds.
+Round-tripping the full model would freeze today's deny list and provider table into
+your file permanently, so a future security default could never reach you.
+
+**Writes are atomic and validated.** The edited settings round-trip through
+`Settings.model_validate` before anything touches disk, then land via a temp file and
+`os.replace`. A malformed settings file makes `load_settings` raise and the CLI exit 2 —
+failing closed is right, but only if we never cause it ourselves.
+
+**Secrets are named, never stored.** Provider credentials are edited as the env var
+*name*, and the written config has an `api_key_env` key and no `api_key` value at all —
+a config UI with a "paste your key here" box writes secrets into a JSON file that gets
+committed, which is how keys leak. The ✓/✗ indicator reports the name and a boolean,
+never the value, a prefix, or a length. MCP `env` values are literal by protocol necessity, so a server carrying any is
+forced to `settings.local.json` and refused a shared file, and the screen creates
+`.turnloop/.gitignore` before writing — otherwise a secret-bearing file can be committed
+before the first session ever runs.
+
+**No agent-reachable route writes settings.** No tool and no hook mutates a settings
+file — which is what makes the deny rules above meaningful instead of decorative.
+`/config` and `/mcp add` are slash commands, and that is safe for a specific reason worth
+stating: `dispatch_command` has exactly one caller, reached from the prompt Input's
+`on_input_submitted`. The model emits tool calls, not typed input, so it cannot reach
+that path. The property lives in the dispatch path rather than in the commands, so a
+future refactor that routes model output through `dispatch_command` would break it
+silently — there is a comment there saying so.
+
+**In-session saves reload only what is safe to reload.** `permission_mode`,
+`permissions`, `max_iterations` and `tool_verbosity` are read from the live `Settings`
+and `PermissionEngine`, so they take effect immediately. `provider`, `providers`,
+`search` and `include_memory` are baked into objects built once at agent construction,
+so the confirmation names them as needing a restart. Reporting "saved" while the old
+permission mode is still being enforced would be worse than saying nothing.
+
+One honest gap: removing a server deletes it from the one file you chose. `deep_merge`
+has no tombstone, so a server also defined in a higher layer stays effective. The screen
+says so rather than pretending otherwise.
+
+### MCP servers are a trust decision
+
+Adding an MCP server is the same class of decision as `npm install`, and turnloop cannot
+check it for you. Two specific reasons, both inherent to the protocol rather than to this
+implementation:
+
+**A stdio server is a program you agreed to run.** `command` and `args` are spawned as a
+child process at every launch, with your full user privileges and any `env` you set. The
+add form states this and requires an explicit confirmation, because a text field labelled
+"command" does not otherwise read like "execute this forever."
+
+**Tool descriptions are untrusted text that enters the model's context.** A server
+advertises its own names and descriptions, and those go into the system prompt verbatim.
+A hostile or compromised server can put instructions there. Nothing in the protocol
+authenticates that text.
+
+What turnloop does about it, which is containment rather than prevention: MCP tools are
+`read_only = False` unconditionally (`mcp/adapter.py`), because the protocol has no
+read-only annotation worth trusting — so they always prompt in `default` mode and are
+refused outright in `plan` mode. A dead or misbehaving server degrades to "that tool is
+unavailable" and never blocks the loop. Connections are lazy and every call is bounded.
+
+None of that helps if you install a server that does exactly what it says. Read what you
+add.
+
 ---
 
 ## Limitations
@@ -948,11 +1076,13 @@ Stated rather than buried:
   that matters. That trade is deliberate: the default has to work with no key at all.
 - **The Anthropic adapter is fixture-tested but has never sent a real request.** It is
   coded against the documented wire format and passes against recorded SSE, which is not
-  the same as verified. It is now the only one: the Gemini adapter is verified live
-  (text, tool calls and images on `gemini-flash-latest`), and OpenAI needs no separate
-  verification because `openai` is `kind="openai_compat"` — the same adapter Groq,
-  NVIDIA, Ollama, Blaxel and the self-hosted GLM endpoint all run through, making it
-  the most exercised code path in the repo.
+  the same as verified. It is now the only one: Gemini is verified through a real
+  multi-turn agent loop on `gemini-flash-latest` — tool calls, edits, file writes and
+  images — and OpenAI needs no separate verification because `openai` is
+  `kind="openai_compat"`, the same adapter Groq, NVIDIA, Ollama, Blaxel and the
+  self-hosted GLM endpoint all run through, making it the most exercised code path in
+  the repo. "Verified" here means multi-turn deliberately: a single-turn check on
+  Gemini passed while the loop was broken. See [Bugs worth reading about](#bugs-worth-reading-about).
 - **`subtle_spec_edge` currently passes for nobody** (0/5 on gpt-4o-mini). The rewrite
   overshot — runs die on collection errors and leave `NotImplementedError`, which is
   failure-to-produce-working-code, not falling for the decoy. It needs another pass.