thunc 0.2.2__tar.gz → 0.2.3__tar.gz

thunc-0.2.3/.github/release-notes/v0.2.2.md

@@ -0,0 +1,74 @@
+thunc 0.2.2 makes **agents use their tools reliably**, especially on Claude Code, and makes calls faster. Agents on Claude Code now make native tool calls instead of writing each action as JSON text, a failed step is retried instead of ending the run, and the agent's tools fill gaps that a new tool-use benchmark found.
+
+| 8 tool-heavy tasks, Claude Sonnet 5.5 | Passed | Seconds per task | $ per task |
+|---|---|---|---|
+| thunc 0.2.1 agents on Claude Code | 12/24 | 99 | 0.084 |
+| **thunc 0.2.2 agents on Claude Code** | **24/24** | **10** | **0.022** |
+| Claude Code itself, for reference | 24/24 | 11 | 0.069 |
+
+On Claude Opus 5.5 both versions passed every task, but 0.2.2 took 15 seconds and $0.051 a task instead of 44 seconds and $0.264.
+
+```bash
+pip install --upgrade thunc
+```
+
+```python
+import thunc
+
+thunc.configure(backend="claude-code")  # agents now make native tool calls here
+fixer = thunc.Agent("fixer", workdir=".", permissions=["write:src/**", "run:pytest"])
+
+
+@fixer.task
+def make_tests_pass() -> str:
+    """Run the tests in services/api and fix what fails. Say what you changed."""
+    ...
+
+
+run = fixer.run(make_tests_pass)  # run.commands, run.files_changed, and any retries in run.session
+```
+
+```bash
+thunc run --profile my_script.py  # where the time went: model time, thunc's own, per tool
+```
+
+**Agents on Claude Code make native tool calls** ([#46](https://github.com/Eltarras/thunc/pull/46))
+- The agent's tools are an MCP server that one `claude -p` process per run calls, and thunc carries out each call with its own tools, permissions and run record. Before, the model wrote each action as JSON text. Current models slip back into their trained tool calls: they invented tool results and ran on to the timeout, or the CLI refused a tool call it couldn't parse.
+- Calls from one model reply count as one step. A turn without a tool call gets a nudge, and a turn that ends in an error gets a second chance, both in the same session.
+- **Fallback:** with a `claude` CLI too old for these options, or with MCP servers turned off by a policy, a run falls back to the text protocol with a warning. `protocol="native"` raises instead, and `protocol="text"` keeps the old way.
+- The CLI runs in the agent's `workdir`, so the environment details it adds to the prompt name the right folder.
+
+**Steadier runs** ([#46](https://github.com/Eltarras/thunc/pull/46))
+- **A failed step is retried** twice before the run fails, and each retry is logged in the run record. This covers timeouts, lost connections, rate limits, server errors and CLI calls that end in an error (`thunc.errors.TransientError`). Before, one bad call ended the run.
+- A text-protocol step on Claude Code or Codex now times out after 120 seconds instead of the whole 300-second `timeout`.
+
+**Better tools for agents** ([#46](https://github.com/Eltarras/thunc/pull/46))
+- **`run` takes `cwd`**: a folder inside `workdir` to run the command in.
+- **The `shell` permission** (opt-in) runs command lines through the system shell, so pipes, `&&`, `cd` and redirects work. It can't be combined with `!run:` rules, since a shell command line can't be checked word by word.
+- **`search` takes `glob`**: `*.py` matches by file name, `src/**/*.ts` by path.
+- **Git-aware `list` and `search`**: in a git repository they leave out what git ignores, so a stale `build/` copy no longer crowds out the real source.
+- **Long command output keeps its start and its end**, so an agent sees the first error as well as the summary.
+
+**Faster calls** ([#45](https://github.com/Eltarras/thunc/pull/45))
+- **The `anthropic` and `openai` backends reuse their connections**: one SDK client per process instead of a new TCP and TLS handshake each call. In a local benchmark with 60 ms of connection setup, 20 calls in a row went from 1.47 s to 68 ms.
+- **Text-protocol agents can act several times per reply** (Codex and `protocol="text"`), with a JSON array of independent actions. On Codex, the prompt eval took fewer replies (fix / review / analysis: 6.0 / 4.8 / 5.0 → 5.0 / 3.0 / 3.6) and less time (37 / 27 / 27 s → 29 / 19 / 21 s).
+- **The `codex` backend returns as soon as the answer arrives**, without waiting about 0.4 s for Codex to shut down.
+- **`thunc run --profile SCRIPT`** (or `-m module`) reports where a program's time went, per function: calls, cache hits, retries, failures, model time against thunc's own, and time per tool for agents. `python -m benchmarks` runs a dependency-free benchmark suite.
+
+**Tested**
+- Offline tests run on Python 3.10–3.14 on Ubuntu, and on Windows. Temporal integration tests run on Python 3.10 and 3.14.
+- The MCP path has an end-to-end test with a fake `claude` that starts the real tool server, covering parallel and serial calls, permissions, errors and the fallback.
+- Live: the tool-use benchmark (`live_tests/bench_tooluse.py`, with its report in `live_tests/bench_tooluse_report.md`) on Sonnet 5.5 and Opus 5.5, the prompt eval on Claude Code (45/45), and the live tests on Claude Code.
+- The agent loops on the Claude and OpenAI APIs haven't had a live tool-use benchmark yet.
+
+**Behaviour changes**
+- Agents on `claude-code` make native tool calls by default, and fall back to the text protocol if they can't.
+- In a git repository, `list` and `search` leave out what git ignores. A folder named explicitly is still listed and searched.
+- Long command output keeps its start as well as its end.
+- The `claude-code` backend loads none of your Claude Code settings (`--setting-sources ""`). No `CLAUDE.md`, settings or hooks reach thunc's calls, plain function calls included, so a folder you point an agent at can't instruct it unless you pass `follow=`.
+- Durable runs on Claude Code still use the text protocol.
+- Nothing is removed.
+
+Still beta: expect bugs, and the API may change. Known issues are listed in [CONTRIBUTING.md](https://github.com/Eltarras/thunc/blob/main/CONTRIBUTING.md#known-issues), and every change is in [CHANGELOG.md](https://github.com/Eltarras/thunc/blob/main/CHANGELOG.md).
+
+**Full changelog:** https://github.com/Eltarras/thunc/compare/v0.2.1...v0.2.2

thunc-0.2.3/.github/release-notes/v0.2.3.md

@@ -0,0 +1,80 @@
+thunc 0.2.3 is the last 0.2 release. It makes **native tool calls the way agents work wherever they run**: on Codex now, as on Claude Code, and in durable runs on Claude Code, which pick up after a crash mid-call. Durable agents can take `tools=`, the Claude API agent path no longer loses runs to `max_tokens` or a stalled reply, and `edit` can change many places at once.
+
+| 8 tool-heavy tasks, Claude Sonnet 5.5, 3 runs each | Passed | Seconds per task | $ per task |
+|---|---|---|---|
+| thunc 0.2.2 agents, text protocol (Codex, durable runs, fallbacks) | 20/24 | 47 | 0.084 |
+| **thunc 0.2.3 agents, text protocol** | **24/24** | **27** | 0.082 |
+| thunc 0.2.3 agents on Claude Code, native calls | 24/24 | 8 | 0.021 |
+| Claude Code itself, for reference | 24/24 | 10 | 0.078 |
+
+Through the Claude API, thunc's agents passed 8 of 8 on Sonnet 5.5 ($0.023 a task) and on Opus 5.5 ($0.049 a task). On Codex, native calls took 30 seconds a task, against 45 for the text protocol 0.2.2 used there and 27 for Codex itself (16 of 16 each).
+
+```bash
+pip install --upgrade thunc
+```
+
+```python
+import thunc
+
+thunc.configure(backend="codex")  # agents now make native tool calls here too
+
+
+def find_issue(title: str) -> int:  # a tool is your own code, with a docstring for the model
+    """Find an open issue by title. Returns its number, or 0."""
+    return tracker.find(title)
+
+
+triage = thunc.Agent("triage", workdir=".", tools=[find_issue], effort="high")
+
+
+@triage.task
+def flaky_tests() -> list[str]:
+    """Run the tests three times and list the ones that fail only sometimes."""
+    ...
+```
+
+```python
+# On a Temporal worker: durable runs take the agent's own tools now, and name those that may run
+# again after a crash.
+registry.agent_task("triage", flaky_tests, version="1", workspace_id="repo", retry_safe_tools=["find_issue"])
+```
+
+**Native tool calls on Codex** ([#55](https://github.com/Eltarras/thunc/pull/55))
+- The agent's tools are an MCP server that Codex calls, through the same relay as Claude Code: thunc carries out each call with its own tools, permissions and run record. Codex's own tools and your `~/.codex` config stay out, its sandbox stays read-only, and only thunc's server is approved to run without asking.
+- A turn that ends without `finish`, or fails, is continued with `codex exec resume`. The run's Codex session is deleted when the run ends.
+- **Fallback:** when Codex can't start them, a run uses the text protocol with a warning. `protocol="native"` raises instead, and `protocol="text"` keeps the old way.
+
+**Durable runs** ([#56](https://github.com/Eltarras/thunc/pull/56), [#57](https://github.com/Eltarras/thunc/pull/57))
+- **On Claude Code, native calls in segments.** One activity keeps one `claude -p` process for many model replies, and checkpoints the run and Claude Code's session before each reply's calls. If the worker stops or the CLI dies, the retried activity restores the session and continues it with `--resume`. The call that was in flight, asked for again, gets its old journal entry: it's replayed, waits for `resolve()`, or runs. Never twice.
+- **`tools=`.** Each call of the agent's own functions is journaled like a command: recorded before it runs and after, replayed when completed, and waiting for `resolve()` if a worker stopped mid-call. `retry_safe_tools=` names the ones that may simply run again.
+
+**The Claude API agent path** ([#52](https://github.com/Eltarras/thunc/pull/52))
+- **`Agent(effort=...)`** on every backend. Claude 4.6 and later on the API get `"high"` by default; Claude Opus 5.5's own default is `"medium"`, which is low for agentic coding.
+- Replies are streamed with room for 64,000 tokens. A reply cut off at `max_tokens` gets an error result for its calls instead of ending the run, `pause_turn` carries on, and a reply that sends nothing for `timeout` seconds is stopped and asked again (one Opus reply in the benchmark sent nothing for an hour).
+- Old tool results are cleared on long runs (context editing), tools are strict where the model and schema allow, and connection errors, rate limits and server errors are retried as a step.
+
+**Steadier agents everywhere** ([#51](https://github.com/Eltarras/thunc/pull/51), [#52](https://github.com/Eltarras/thunc/pull/52), [#53](https://github.com/Eltarras/thunc/pull/53))
+- **The text protocol reads replies that aren't only the action**: the first complete action amid prose, a fence, `<invoke>` markup or made-up results, with a note to the model to keep to JSON. On Claude Code, a text step stops as soon as its action has arrived.
+- **`finish` in the same reply as other calls is refused** (except beside `remember`): in the benchmark, a run returned a guess written before its own read came back.
+- **The model is told when few steps are left**, in its last three replies before `max_steps`.
+
+**Better tools** ([#50](https://github.com/Eltarras/thunc/pull/50), [#51](https://github.com/Eltarras/thunc/pull/51), [#49](https://github.com/Eltarras/thunc/pull/49))
+- **`edit` takes `replace_all`, and `edits`** for several changes to one file in one call, all made or none.
+- **`edit` no longer needs a prior `read`**: it only changes text the agent quotes exactly. `write` still replaces only a file read with `read`.
+- **Large system prompts work on Claude Code**: the prompt goes in a file, not on the command line, where large `follow=` files could pass the operating system's limit.
+
+**Tested**
+- Offline tests run on Python 3.10–3.14 on Ubuntu, and on Windows; Temporal integration tests on Python 3.10 and 3.14, including a Claude Code run whose CLI dies mid-run. Tests can't reach a real `claude`, `codex` or `jev`.
+- Live: the tool-use benchmark on Claude Code (Sonnet 5.5), the Claude API (Sonnet 5.5 and Opus 5.5) and Codex, with the results in `live_tests/bench_tooluse_report.md`; a durable run on real Claude Code with the CLI killed after its first tool result, which finished with each effect done once.
+
+**Behaviour changes**
+- Agents on `codex` make native tool calls by default, and fall back to the text protocol if they can't.
+- Durable runs on `claude-code` make native tool calls. Runs already in progress keep the text protocol.
+- Agents on the Claude API think at effort `high` on Claude 4.6 and later.
+- `edit` no longer needs a prior `read`; `write` still does.
+- `finish` in the same reply as other calls is refused, except beside `remember`.
+- Nothing is removed.
+
+**Known issues:** on Codex, native calls count each tool call as a step, so a long task reaches `max_steps` sooner, and their tokens aren't reported. Durable runs on Codex use the text protocol. On a fix in a long file, native calls take about twice Claude Code's steps. The full list is in [CONTRIBUTING.md](https://github.com/Eltarras/thunc/blob/main/CONTRIBUTING.md#known-issues), and every change is in [CHANGELOG.md](https://github.com/Eltarras/thunc/blob/main/CHANGELOG.md).
+
+**Full changelog:** https://github.com/Eltarras/thunc/compare/v0.2.2...v0.2.3

thunc-0.2.3/.github/workflows/release-notes.yml

@@ -0,0 +1,46 @@
+name: Release notes
+
+# Run by hand (Actions > Release notes > Run workflow) with a version like 0.2.2. It writes the
+# notes in .github/release-notes/v<version>.md to that release, and sets its title to
+# "v<version> (beta)". A release that doesn't exist yet is created as a draft pre-release on the
+# commit the workflow runs from, for you to review and publish. Editing or drafting a release
+# doesn't trigger publish.yml, which runs only when you publish one.
+
+on:
+  workflow_dispatch:
+    inputs:
+      version:
+        description: "Version, like 0.2.2"
+        required: true
+
+permissions:
+  contents: write  # create and edit releases
+
+jobs:
+  notes:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Write the notes to the release
+        env:
+          GH_TOKEN: ${{ github.token }}
+          VERSION: ${{ inputs.version }}
+        run: |
+          if [[ ! "$VERSION" =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
+            echo "::error::version must look like 0.2.2, not '$VERSION'"
+            exit 1
+          fi
+          tag="v$VERSION"
+          notes=".github/release-notes/$tag.md"
+          if [[ ! -f "$notes" ]]; then
+            echo "::error::$notes doesn't exist; add it first"
+            exit 1
+          fi
+          if gh release view "$tag" > /dev/null 2>&1; then
+            gh release edit "$tag" --title "$tag (beta)" --notes-file "$notes"
+            echo "Updated the notes of $tag."
+          else
+            gh release create "$tag" --draft --prerelease --target "$GITHUB_SHA" \
+              --title "$tag (beta)" --notes-file "$notes"
+            echo "Created $tag as a draft pre-release."
+          fi

{thunc-0.2.2 → thunc-0.2.3}/CHANGELOG.md

@@ -3,6 +3,123 @@
 All notable changes to thunc. The full notes for each release are on the
 [releases page](https://github.com/Eltarras/thunc/releases).
 
+## 0.2.3 (beta)
+
+**Native tool calls everywhere agents run, durable runs that keep them, and the last of 0.2.**
+Agents on Codex make native tool calls through the same MCP relay as Claude Code, durable runs on
+Claude Code do too and pick up after a crash mid-call, and durable agents can take `tools=`. On the
+Claude API, agents stream their replies, think at effort `high`, and no longer lose a run to
+`max_tokens` or a stalled reply. `edit` can replace every occurrence or make several changes at
+once, and no longer needs a prior `read`. In the tool-use benchmark (`live_tests/bench_tooluse.py`,
+8 tasks, Claude Sonnet 5.5, 3 runs each), every harness passed 24 of 24, the text protocol included
+(20 of 24 in 0.2.2) in about half the time; through the Claude API, Sonnet 5.5 and Opus 5.5 passed
+8 of 8; on Codex, native calls took 30 seconds a task against 45 for the text protocol.
+
+### Behavior changes
+
+- **Agents on `codex` make native tool calls**, as on Claude Code since 0.2.2 (see Added). When
+  Codex can't start them, a run falls back to the text protocol with a warning; `protocol="text"`
+  keeps the old way, and durable runs on Codex still use it.
+- **`finish` called in the same reply as other calls is refused** (except beside `remember`): its
+  value can't account for results the model hasn't seen yet. The other calls run, and the model is
+  told to call `finish` on its own. In the tool-use benchmark, a run on the text protocol batched
+  `[search, read, finish 0.0]` and returned the guess. Every protocol and durable runs get it.
+- **Agents on the Claude API think at effort `high` by default** on Claude 4.6 and later. Claude
+  Opus 5.5's own default is `medium`, which is low for agentic coding. `effort=` changes it (below).
+- **`edit` no longer needs the file to have been read first.** It only changes text the agent
+  quotes exactly, so it can't overwrite what the agent hasn't seen. With the `shell` permission,
+  agents often read files with `cat`, and `edit` refused them until they read the file again with
+  `read`: 7 times in 24 runs of the tool-use benchmark. A file the agent did read must still not
+  have changed on disk since, and `write` still replaces only a file read with `read` (a file
+  changed by an edit alone still counts as unread). The `run` tool's description, with `shell`, now
+  says to read files with `read`.
+
+### Added
+
+- **Durable runs on Claude Code make native tool calls.** A run goes in segments: one activity keeps
+  one `claude -p` process for many model replies, and before each reply's calls are carried out it
+  saves a checkpoint of the run and of Claude Code's session. If the worker stops or the CLI dies,
+  the retried activity restores the session and continues it with `--resume`; Claude Code marks the
+  call that was in flight as interrupted, the model asks for it again, and it gets the journal entry
+  it had, so it's replayed, waits for `resolve()`, or runs (one the model doesn't ask for again
+  keeps its entry). The session is removed when the run ends. When Claude Code can't start native
+  calls, the run goes on with the text protocol. Runs already in progress keep the text protocol.
+- **Durable agents can have `tools=`.** Each call of one of the agent's own functions is journaled
+  like a command: the intent is recorded before it runs and its result after, so a retried activity
+  replays the result instead of calling it again, and a call interrupted by a worker stopping waits
+  for `resolve()`. `registry.agent_task(..., retry_safe_tools=["find_issue"])` names the tools that
+  may run again instead. A tool's description, arguments and retry marking are part of the task's
+  fingerprint, so changing one needs a new version; tasks without tools keep their fingerprint.
+- **Native calls on `codex`**: the agent's tools are an MCP server (thunc's relay, given with
+  `-c mcp_servers.thunc.*`) that Codex calls; thunc carries out each call with its own tools,
+  permissions and run record. Each `codex exec` is a turn: one that ends without `finish` is
+  continued with `codex exec resume`, as is one that fails (twice at most). Codex's own tools and
+  your `~/.codex` config stay out and its sandbox stays read-only; only thunc's server is approved
+  to run without asking, with a tool timeout above `command_timeout`. Resuming needs the session
+  saved, so thunc deletes the run's Codex session (`codex delete --force`) when the run ends.
+- **`Agent(effort=...)`**: `"low"`, `"medium"`, `"high"`, `"xhigh"` or `"max"`, on every backend
+  (`output_config.effort` on the Claude API, `reasoning.effort` on OpenAI, `--effort` on Claude Code,
+  `model_reasoning_effort` on Codex; the last two go up to `"xhigh"`). Recorded in `agent.json` only
+  when set, so durable tasks registered without it keep their fingerprint.
+- **The model is told when few steps are left.** In its last three replies before `max_steps`, the
+  last tool result says how many replies remain, so the model can finish with what it has instead
+  of being cut off. Every protocol and durable runs get it; the run record keeps each tool's output.
+- **`edit` can replace every occurrence, and make several changes in one call.** With
+  `"replace_all": true`, every occurrence of `old` is replaced and the result gives the count. With
+  `"edits": [{"old": ..., "new": ..., "replace_all"?: ...}, ...]` (at most 50) instead of `old` and
+  `new`, the changes apply in order, each to the text the ones before it left; if one fails, none is
+  made, and the error names it. In the tool-use benchmark, models renamed a symbol by writing a
+  throwaway script instead of making 26 separate edits, and took twice Claude Code's turns on a
+  multi-spot fix. In a durable run, a multi-edit is one effect, recovered as a whole.
+
+### Changed
+
+- **The text protocol reads replies that aren't only the action** (finding 1 of the tool-use
+  benchmark report). Models trained for native tool calls often wrap the action in prose, a code
+  fence or `<invoke>` markup, or carry on past it with results they make up: on Sonnet 5.5, 25% of
+  text-protocol replies were sent back as "not valid JSON" with a correct action inside. Now the
+  first complete action (or array of them) in the reply is used, with literal newlines in its
+  strings accepted, and a reply written only as `<invoke name="...">` markup is read as its calls,
+  each argument in its tool's type (or as one JSON `args` parameter). A reply with no action in it
+  is still sent back, as before. A reply read this way runs, but its results carry a note to reply
+  with the JSON action alone: without it, a model that slipped into markup was never corrected, and
+  on Sonnet 5.5 fell into repeating empty markup until the step timed out.
+  This is the text protocol on Codex, `protocol="text"`, durable runs on Codex, and Claude
+  Code's fallback from native calls.
+- **A text-protocol step on Claude Code stops once its action is complete.** The reply is streamed
+  (`--output-format stream-json --include-partial-messages`) and the CLI is stopped as soon as a
+  complete action has arrived, rather than left to make up the tool's result until the step times
+  out (7 of 8 replayed first steps on Sonnet ran past 120 seconds that way). A batch that has begun
+  is waited for, and two blocks of `<invoke>` markup end the step too (a model repeating itself).
+  Plain `@thunc.function` calls on Claude Code aren't streamed.
+- **The Claude API agent path keeps runs going** (finding 7 of the tool-use benchmark report):
+  - Replies are streamed with `max_tokens=64000` (was 16,000 without streaming), so a large write
+    fits.
+  - A reply cut off at `max_tokens` no longer ends the run: its tool calls aren't run and get an
+    error result saying so, and the model is asked again. Two in a row end the run.
+  - `pause_turn` is asked to carry on (up to 6 times in a row) instead of ending the run.
+    `model_context_window_exceeded` ends it with a message that says so.
+  - On Claude 4.6 and later, the API clears old tool results on long runs (context editing, beta
+    `context-management-2025-06-27`).
+  - Tools are `strict` (arguments guaranteed to match their schema) on the models that support it,
+    when the schema allows it: the built-in tools except `edit`, `remember`, and `finish` and custom
+    tools whose schema is closed.
+  - A reply that sends nothing for `timeout` seconds (300 by default) is stopped and asked again. The
+    SDK's read timeout doesn't catch it, as the API's keep-alive pings count as reading: in the
+    tool-use benchmark, one reply on Claude Opus 5.5 sent nothing for an hour.
+  - A lost connection, a rate limit or a server error on the Claude and OpenAI APIs is retried as a
+    step, like the CLI backends' errors, instead of ending the run.
+
+### Fixed
+
+- **A large system prompt no longer stops the `claude-code` backend from starting.** It went on the
+  command line, so large `follow=` files and memory could pass the operating system's limit on its
+  length (128 KB for one argument on Linux, 32,767 characters for the whole line on Windows), and
+  starting `claude` failed with a raw `OSError: Argument list too long`. The prompt now goes in a
+  temporary file (`--system-prompt-file`), as it already did for agents' native calls and on Codex.
+  This covers `@thunc.function` and `thunc.call`, agents on the text protocol, and durable runs on
+  Claude Code. A command line that is still too long raises a `ThuncError` that gives its size.
+
 ## 0.2.2 (beta)
 
 **Agents that use their tools reliably, and faster calls.** Agents on Claude Code make native tool

{thunc-0.2.2 → thunc-0.2.3}/CONTRIBUTING.md

@@ -86,8 +86,9 @@ THUNC_TEMPORAL_TESTS=1 .venv/bin/pytest -c pytest-temporal.ini tests/temporal
 5. Agents work on any text backend through the JSON text protocol. For native tool calls, add a
    `Conversation` for the API in `thunc/native.py`, add the backend to `native.NATIVE`, and pick
    the class where `thunc/agent.py` builds the conversation. Test it like `tests/test_native.py`.
-   A CLI that can call MCP tools can get native calls the way Claude Code does
-   (`thunc/claude_code.py`, tested with a fake CLI in `tests/test_claude_code_agent.py`).
+   A CLI that can call MCP tools can get native calls the way Claude Code and Codex do: through the
+   relay in `thunc/relay.py` (see `thunc/claude_code.py` and `thunc/codex.py`, tested with fake CLIs
+   in `tests/test_claude_code_agent.py` and `tests/test_codex_agent.py`).
    Raise `TransientError` for failures worth asking again, so agent runs retry them.
    Agents and durable runs refuse typed backends.
 6. Run `THUNC_BACKEND=<name> .venv/bin/pytest live_tests` against the real service, and say in
@@ -153,20 +154,20 @@ no reliable way to tell them from a real one. Only an empty reply is retried.
 
 **Open: agents and durable runs.**
 
-- Durable runs on `claude-code` use the JSON text protocol, not native calls: the MCP path keeps
-  one CLI process for the whole run, which a durable step can't snapshot. The text protocol is the
-  weaker one: in `live_tests/bench_tooluse.py` on Sonnet 5.5 it passed 12 of 24 runs, and 20 of 24
-  with step retries (measured before action arrays), against 24 of 24 for native calls.
-- The `shell` permission isn't tested on Windows: its test is skipped there, so `cmd /c` has never
-  run in CI.
-- With `shell`, a file read with `cat` doesn't count as read for `edit`, which refuses until the
-  agent reads it with `read` (the no-blind-overwrite rule). Agents work around it with a short
-  `read`, at the cost of a step.
-- The agent loops on the Claude and OpenAI APIs have no live tool-use benchmark yet (only
-  `live_tests/eval_prompts.py`); their `max_tokens`, effort and stop-reason handling were reviewed
-  from the code only (`live_tests/bench_tooluse_report.md`, finding 7).
-- Durable agents can't use `tools=` yet: the effects of the program's own functions can't be
-  journaled.
+- On Codex, native calls count each tool call as a step: Codex's events don't say which calls came
+  from the same model reply. A long task reaches `max_steps` sooner than on Claude Code (22 steps on
+  `rename` in the tool-use benchmark, against `max_steps=40`).
+- Tokens aren't reported for native runs on Codex: `codex exec --json` reports usage at the end of
+  a turn, and a run ends inside one when the model calls `finish`.
+- Durable runs on `codex` use the JSON text protocol, not native calls.
+- On a fix in a long file (`deep_fix` in the tool-use benchmark), native calls take about twice
+  Claude Code's steps (8 against 4.3), reading around the file in pages. A larger `read` limit is
+  the next thing to measure.
+- Durable runs on Claude Code save the whole session file at each checkpoint, so a long run's saved
+  state grows with every reply, and counts toward the 16 MiB limit. A CLI that dies leaves Claude
+  Code's own `~/.claude/sessions/<pid>.json` behind.
+- The `shell` permission's own test (pipes, `cd`, redirects) is skipped on Windows; only a single
+  command line runs through `cmd /c` in CI.
 - Durable runs have no garbage collection: the journal, transcript artifacts and request-ID
   tombstones are kept forever. There's no context summarization either, so a long run fails once
   its saved state passes 16 MiB.

{thunc-0.2.2 → thunc-0.2.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: thunc
-Version: 0.2.2
+Version: 0.2.3
 Summary: think + function: call an LLM like a typed Python function.
 Project-URL: Homepage, https://eltarras.github.io/thunc/
 Project-URL: Documentation, https://eltarras.github.io/thunc/docs/
@@ -203,8 +203,8 @@ or takes `--cache-dir`; it can't see a `configure(cache_dir=...)` in your code.
   `pip install "thunc[openai]"`. The default model is `gpt-5.5`. `OPENAI_BASE_URL` points it at
   any server that speaks the OpenAI Responses API.
 - `claude-code` and `codex` call your local CLI login, and are meant for cheap testing.
-  Both run with their own tools turned off, so the model can only answer; an agent on
-  `claude-code` gets only its thunc tools, as native calls (see Agents). `codex` also ignores
+  Both run with their own tools turned off, so the model can only answer; an agent on either
+  gets only its thunc tools, as native calls (see Agents). `codex` also ignores
   `~/.codex/config.toml` (your MCP servers, plugins, `notify` command and model settings); your
   login still works. Pick the model with `configure(model=...)` or `model=`.
 - `jev` is TypeSafe's [Jev](https://typesafe.ai/blog/introducing-system-one-models-and-jev)
@@ -305,10 +305,15 @@ calls are native too: the agent's tools are an MCP server that one `claude -p` p
 calls, while thunc carries out each call with its own tools, permissions and records. If Claude Code
 can't start them (an older `claude` CLI, or MCP servers turned off by a policy), the run uses the
 text protocol below instead, with a warning, and so do later runs in the process;
-`protocol="native"` fails instead. On Codex the model replies with JSON actions as text: one at a
-time, or several independent ones (reading three files) as a JSON array, which saves turns.
-`protocol="text"` uses that way on any backend, for example with a server behind `OPENAI_BASE_URL`
-that has no function calling. (Durable runs on Claude Code use it too.)
+`protocol="native"` fails instead. On Codex it's the same: each `codex exec` is a turn in which
+the model calls the agent's tools through the MCP server, a turn that ends without `finish` is
+continued with `codex exec resume`, Codex's own tools stay off and its sandbox read-only, and the
+run's Codex session is deleted when the run ends. With `protocol="text"` the model replies with
+JSON actions as text instead: one at a time, or several independent ones (reading three files) as
+a JSON array, which saves turns. That works on any backend, for example with a server behind
+`OPENAI_BASE_URL` that has no function calling. (Durable runs on Codex use it.) A reply that wraps its
+action in prose or tool-call markup, or carries on past it, is read for its first complete action,
+and on Claude Code the step stops as soon as that action has arrived.
 The `jev` backend only answers typed questions and cannot run agents, even for a task returning
 `bool` or `Literal[...]`. An agent run using it raises `ThuncError` before creating any run files
 or calling a backend. Use `@thunc.function` or `thunc.call` for Jev questions.
@@ -333,14 +338,18 @@ or calling a backend. Use `@thunc.function` or `thunc.call` for Jev questions.
   the run carries on. Bad rules fail when the agent is declared.
 - **Tools:** `list`, `read` and `search` (a regular expression, optionally limited with a `glob`
   such as `*.py`); `write` (create a file, or replace one) and `edit` (replace text that appears
-  exactly once) when a write rule allows it; `run` when a run or shell rule allows it; and
+  exactly once, or every occurrence with `replace_all`; several changes to one file can go in one
+  call as `edits`, all made or none) when a write rule allows it; `run` when a run or shell rule
+  allows it; and
   `remember`. Every path must stay inside `workdir`: `..`, absolute paths and symlinks that point
   outside are refused, and the rules are checked on where a link really leads. Files the agent may
   not read are left out of `list` and `search`, and so is what git ignores, in a git repository
   (build output, caches, vendored code); a folder named explicitly is still listed and searched.
-- **No blind overwrites.** A file is only replaced or edited after the agent read it in the same
-  run, and only if it hasn't changed on disk since. There is no undo, so run agents that write in a
-  git repository with a clean tree, and review their changes with `git diff`.
+- **No blind overwrites.** A file is only replaced (`write`) after the agent read it with `read` in
+  the same run, and only if it hasn't changed on disk since. An `edit` needs no read, because it
+  only changes text the agent quotes exactly, but a file the agent did read must not have changed
+  since. There is no undo, so run agents that write in a git repository with a clean tree, and
+  review their changes with `git diff`.
 - **Commands** run in `workdir`, or in a folder inside it given as `cwd`. Without the `shell`
   permission there's no shell, so `&&`, pipes, `cd`, redirects and `$VARIABLES` don't work (the
   agent is told). They get a minimal environment: `PATH`, `HOME`, the locale and temp-folder
@@ -379,9 +388,15 @@ or calling a backend. Use `@thunc.function` or `thunc.call` for Jev questions.
   `system=thunc.prompts.CODING + "\n\nTarget Python 3.10."`.
 - **Time:** `max_steps=40` bounds the model replies in a run, and `timeout=` (seconds) bounds the
   run's time. It's checked before each model call; a command's time limit is cut to the time left.
+  In its last three replies before `max_steps`, the model is told how many are left, so it can
+  finish with what it has.
+- **`effort=`** sets how hard the model thinks: `"low"`, `"medium"`, `"high"`, `"xhigh"` or `"max"`
+  (`openai` and `codex` go up to `"xhigh"`). By default it's `"high"` on the `anthropic` backend for
+  Claude 4.6 and later (Claude Opus 5.5's own default is `"medium"`, low for agentic coding), and
+  each backend's own default elsewhere.
 - **Options:** `thunc.Agent(name, *, workdir, system=None, permissions=(), env=None,
   command_timeout=120, follow=False, protocol=None, tools=(), timeout=None, max_steps=40,
-  retries=2, backend=None, model=None)`, and `@agent.task(instructions=..., ensure=...)`.
+  retries=2, backend=None, model=None, effort=None)`, and `@agent.task(instructions=..., ensure=...)`.
   `@thunc.agent(name, workdir=..., instructions=..., ensure=..., **options)` takes the same options.
   `async def` tasks work.
 - **What happened in a run.** Calling a task returns its value. `agent.run(task, *args)` runs it
@@ -401,7 +416,9 @@ or calling a backend. Use `@thunc.function` or `thunc.call` for Jev questions.
   A step that fails for a reason asking again may fix (a timeout, a lost connection, a rate limit,
   a server error, a CLI call that ended in an error) is retried twice, after 2 and 4 seconds, and
   each retry is in the run's record. A text-protocol step on Claude Code or Codex may take 120
-  seconds before it's retried. With tracing on, each run is also one line with every model reply.
+  seconds before it's retried. On the Claude API, a reply cut off at `max_tokens` doesn't end the
+  run: its tool calls get an error result saying so (twice in a row does). With tracing on, each run
+  is also one line with every model reply.
 
 **How the prompt was tested.** `python -m live_tests.eval_prompts --backend anthropic` runs three
 small tasks (fix a bug, review a diff, answer a question about a repo) with three versions of the
@@ -458,8 +475,9 @@ print(run.value)
 ```
 
 Durable mode requires a Temporal service, a worker, and persistent storage on the
-same volume. File changes and memory updates use recovery receipts. Commands with
-uncertain outcomes pause for operator resolution instead of blindly running twice.
+same volume. File changes and memory updates use recovery receipts. Commands, and the agent's
+own `tools=` functions, with uncertain outcomes pause for operator resolution instead of blindly
+running twice (`retry_safe_tools=` names functions that may run again).
 Temporal does not back up your workspace or guarantee exactly-once external effects.
 
 The [Temporal guide and runnable example](examples/temporal/README.md) cover service
@@ -491,6 +509,8 @@ thunc/
   runs.py        thunc.Run and AgentError: what a run did
   native.py      how a run talks to its backend: native tool calls or the text protocol
   claude_code.py native tool calls on Claude Code, through an MCP server (mcp_relay.py)
+  codex.py       native tool calls on Codex, the same way
+  relay.py       the run's end of the MCP server: the connection the calls come through
   store.py       the agent's folder: memory, settings, run records, the lock
   prompts.py     the agent's system prompt
   __main__.py    the thunc command: thunc run [--profile], thunc cache list / clear

{thunc-0.2.2 → thunc-0.2.3}/README.md

@@ -168,8 +168,8 @@ or takes `--cache-dir`; it can't see a `configure(cache_dir=...)` in your code.
   `pip install "thunc[openai]"`. The default model is `gpt-5.5`. `OPENAI_BASE_URL` points it at
   any server that speaks the OpenAI Responses API.
 - `claude-code` and `codex` call your local CLI login, and are meant for cheap testing.
-  Both run with their own tools turned off, so the model can only answer; an agent on
-  `claude-code` gets only its thunc tools, as native calls (see Agents). `codex` also ignores
+  Both run with their own tools turned off, so the model can only answer; an agent on either
+  gets only its thunc tools, as native calls (see Agents). `codex` also ignores
   `~/.codex/config.toml` (your MCP servers, plugins, `notify` command and model settings); your
   login still works. Pick the model with `configure(model=...)` or `model=`.
 - `jev` is TypeSafe's [Jev](https://typesafe.ai/blog/introducing-system-one-models-and-jev)
@@ -270,10 +270,15 @@ calls are native too: the agent's tools are an MCP server that one `claude -p` p
 calls, while thunc carries out each call with its own tools, permissions and records. If Claude Code
 can't start them (an older `claude` CLI, or MCP servers turned off by a policy), the run uses the
 text protocol below instead, with a warning, and so do later runs in the process;
-`protocol="native"` fails instead. On Codex the model replies with JSON actions as text: one at a
-time, or several independent ones (reading three files) as a JSON array, which saves turns.
-`protocol="text"` uses that way on any backend, for example with a server behind `OPENAI_BASE_URL`
-that has no function calling. (Durable runs on Claude Code use it too.)
+`protocol="native"` fails instead. On Codex it's the same: each `codex exec` is a turn in which
+the model calls the agent's tools through the MCP server, a turn that ends without `finish` is
+continued with `codex exec resume`, Codex's own tools stay off and its sandbox read-only, and the
+run's Codex session is deleted when the run ends. With `protocol="text"` the model replies with
+JSON actions as text instead: one at a time, or several independent ones (reading three files) as
+a JSON array, which saves turns. That works on any backend, for example with a server behind
+`OPENAI_BASE_URL` that has no function calling. (Durable runs on Codex use it.) A reply that wraps its
+action in prose or tool-call markup, or carries on past it, is read for its first complete action,
+and on Claude Code the step stops as soon as that action has arrived.
 The `jev` backend only answers typed questions and cannot run agents, even for a task returning
 `bool` or `Literal[...]`. An agent run using it raises `ThuncError` before creating any run files
 or calling a backend. Use `@thunc.function` or `thunc.call` for Jev questions.
@@ -298,14 +303,18 @@ or calling a backend. Use `@thunc.function` or `thunc.call` for Jev questions.
   the run carries on. Bad rules fail when the agent is declared.
 - **Tools:** `list`, `read` and `search` (a regular expression, optionally limited with a `glob`
   such as `*.py`); `write` (create a file, or replace one) and `edit` (replace text that appears
-  exactly once) when a write rule allows it; `run` when a run or shell rule allows it; and
+  exactly once, or every occurrence with `replace_all`; several changes to one file can go in one
+  call as `edits`, all made or none) when a write rule allows it; `run` when a run or shell rule
+  allows it; and
   `remember`. Every path must stay inside `workdir`: `..`, absolute paths and symlinks that point
   outside are refused, and the rules are checked on where a link really leads. Files the agent may
   not read are left out of `list` and `search`, and so is what git ignores, in a git repository
   (build output, caches, vendored code); a folder named explicitly is still listed and searched.
-- **No blind overwrites.** A file is only replaced or edited after the agent read it in the same
-  run, and only if it hasn't changed on disk since. There is no undo, so run agents that write in a
-  git repository with a clean tree, and review their changes with `git diff`.
+- **No blind overwrites.** A file is only replaced (`write`) after the agent read it with `read` in
+  the same run, and only if it hasn't changed on disk since. An `edit` needs no read, because it
+  only changes text the agent quotes exactly, but a file the agent did read must not have changed
+  since. There is no undo, so run agents that write in a git repository with a clean tree, and
+  review their changes with `git diff`.
 - **Commands** run in `workdir`, or in a folder inside it given as `cwd`. Without the `shell`
   permission there's no shell, so `&&`, pipes, `cd`, redirects and `$VARIABLES` don't work (the
   agent is told). They get a minimal environment: `PATH`, `HOME`, the locale and temp-folder
@@ -344,9 +353,15 @@ or calling a backend. Use `@thunc.function` or `thunc.call` for Jev questions.
   `system=thunc.prompts.CODING + "\n\nTarget Python 3.10."`.
 - **Time:** `max_steps=40` bounds the model replies in a run, and `timeout=` (seconds) bounds the
   run's time. It's checked before each model call; a command's time limit is cut to the time left.
+  In its last three replies before `max_steps`, the model is told how many are left, so it can
+  finish with what it has.
+- **`effort=`** sets how hard the model thinks: `"low"`, `"medium"`, `"high"`, `"xhigh"` or `"max"`
+  (`openai` and `codex` go up to `"xhigh"`). By default it's `"high"` on the `anthropic` backend for
+  Claude 4.6 and later (Claude Opus 5.5's own default is `"medium"`, low for agentic coding), and
+  each backend's own default elsewhere.
 - **Options:** `thunc.Agent(name, *, workdir, system=None, permissions=(), env=None,
   command_timeout=120, follow=False, protocol=None, tools=(), timeout=None, max_steps=40,
-  retries=2, backend=None, model=None)`, and `@agent.task(instructions=..., ensure=...)`.
+  retries=2, backend=None, model=None, effort=None)`, and `@agent.task(instructions=..., ensure=...)`.
   `@thunc.agent(name, workdir=..., instructions=..., ensure=..., **options)` takes the same options.
   `async def` tasks work.
 - **What happened in a run.** Calling a task returns its value. `agent.run(task, *args)` runs it
@@ -366,7 +381,9 @@ or calling a backend. Use `@thunc.function` or `thunc.call` for Jev questions.
   A step that fails for a reason asking again may fix (a timeout, a lost connection, a rate limit,
   a server error, a CLI call that ended in an error) is retried twice, after 2 and 4 seconds, and
   each retry is in the run's record. A text-protocol step on Claude Code or Codex may take 120
-  seconds before it's retried. With tracing on, each run is also one line with every model reply.
+  seconds before it's retried. On the Claude API, a reply cut off at `max_tokens` doesn't end the
+  run: its tool calls get an error result saying so (twice in a row does). With tracing on, each run
+  is also one line with every model reply.
 
 **How the prompt was tested.** `python -m live_tests.eval_prompts --backend anthropic` runs three
 small tasks (fix a bug, review a diff, answer a question about a repo) with three versions of the
@@ -423,8 +440,9 @@ print(run.value)
 ```
 
 Durable mode requires a Temporal service, a worker, and persistent storage on the
-same volume. File changes and memory updates use recovery receipts. Commands with
-uncertain outcomes pause for operator resolution instead of blindly running twice.
+same volume. File changes and memory updates use recovery receipts. Commands, and the agent's
+own `tools=` functions, with uncertain outcomes pause for operator resolution instead of blindly
+running twice (`retry_safe_tools=` names functions that may run again).
 Temporal does not back up your workspace or guarantee exactly-once external effects.
 
 The [Temporal guide and runnable example](examples/temporal/README.md) cover service
@@ -456,6 +474,8 @@ thunc/
   runs.py        thunc.Run and AgentError: what a run did
   native.py      how a run talks to its backend: native tool calls or the text protocol
   claude_code.py native tool calls on Claude Code, through an MCP server (mcp_relay.py)
+  codex.py       native tool calls on Codex, the same way
+  relay.py       the run's end of the MCP server: the connection the calls come through
   store.py       the agent's folder: memory, settings, run records, the lock
   prompts.py     the agent's system prompt
   __main__.py    the thunc command: thunc run [--profile], thunc cache list / clear