thunc 0.2.0__tar.gz → 0.2.2__tar.gz

{thunc-0.2.0 → thunc-0.2.2}/.github/workflows/ci.yml

@@ -16,11 +16,12 @@ jobs:
       - uses: actions/setup-python@v5
         with:
           python-version: ${{ matrix.python-version }}
-      - run: pip install -e ".[anthropic,openai,dev]"
+      - run: pip install -e ".[anthropic,openai,temporal-test,dev]"
       - run: pytest            # offline tests only; live_tests need a model and are not run in CI
       - run: ruff check .
       - run: ruff format --check .
       - run: mypy --strict thunc
+      - run: mypy --strict --platform win32 thunc
 
   # The lock, process stopping and path handling have code just for Windows.
   test-windows:
@@ -34,3 +35,19 @@ jobs:
       - run: pytest
         env:
           PYTHONIOENCODING: utf-8  # the console's own code page can't print every test id and message
+
+  temporal-integration:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.14"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: pip install -e ".[anthropic,openai,temporal-test,dev]"
+      - name: Real service, restart and replay tests (no providers)
+        run: pytest -c pytest-temporal.ini tests/temporal -q
+        env:
+          THUNC_TEMPORAL_TESTS: "1"

{thunc-0.2.0 → thunc-0.2.2}/.gitignore

@@ -9,3 +9,7 @@ dist/
 *.jsonl
 .thunc_cache/
 .thunc_agents/
+.thunc_temporal/
+.temporal-dev/
+examples/temporal/temporal-state/
+examples/temporal/temporal-workspace/

thunc-0.2.2/CHANGELOG.md

@@ -0,0 +1,186 @@
+# Changelog
+
+All notable changes to thunc. The full notes for each release are on the
+[releases page](https://github.com/Eltarras/thunc/releases).
+
+## 0.2.2 (beta)
+
+**Agents that use their tools reliably, and faster calls.** Agents on Claude Code 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 a benchmark found. In that tool-use benchmark
+(`live_tests/bench_tooluse.py`, 8 tasks, Claude Sonnet 5.5, 3 runs each), agents on Claude Code went
+from 12 of 24 runs passing to 24 of 24, from 99 to 10 seconds a task, and from $0.084 to $0.022 a
+task; Claude Code itself took 11 seconds and $0.069. The API backends also reuse their connections,
+Codex answers return sooner, and `thunc run --profile` shows where a program's time goes.
+
+### Behavior changes
+
+Nothing is removed, but these defaults change:
+
+- **Agents on `claude-code` make native tool calls** (see Added). With a `claude` CLI too old for
+  them, or with MCP servers turned off by a policy, a run falls back to the text protocol with a
+  warning. `protocol="text"` keeps the old way.
+- **`list` and `search` leave out what git ignores** in a git repository (build output, caches,
+  vendored code). A folder named explicitly is still listed and searched.
+- **Long command output keeps its start and its end** (the first error and the summary), not only
+  the 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 an
+  agent's `workdir` can't give it instructions unless `follow=` asks for them.
+
+### Added
+
+- **Native calls on `claude-code`**: the agent's tools are an MCP server that one `claude -p`
+  process per run calls; thunc carries out each call with its own tools, permissions and run
+  record. The CLI runs in the agent's `workdir`. `protocol="text"` keeps the old way, and durable
+  runs on Claude Code still use it. When Claude Code can't start native calls (an older CLI, or MCP
+  servers turned off by a policy), a run falls back to the text protocol with a warning and a
+  `fallback` entry in its record; `protocol="native"` raises instead.
+- **`run` takes `cwd`**, a folder inside `workdir` to run the command in.
+- **The `shell` permission** runs command lines through the system shell, so pipes, `&&`, `cd`
+  and redirects work. Off by default; it can't be combined with `!run:` rules.
+- **`search` takes `glob`** (`*.py` by file name, `src/**/*.ts` by path) to limit the files
+  searched.
+- **`thunc run --profile`**: runs a script (or `-m module`) and prints a performance report to
+  stderr when it ends: per function, calls, cache hits, retries, failures, total/mean/p95/max time
+  and the split between model time and thunc's own; for agents, steps and time in each tool; and
+  the share of wall time spent in thunc, with the overlap from `thunc.map`.
+
+### Changed
+
+- **A failed step is retried.** A timeout, lost connection, rate limit, server error or CLI call
+  that ended in an error (`thunc.errors.TransientError`) is retried twice in an agent run, with a
+  note in the run record, before the run fails. A text-protocol step on Claude Code or Codex may
+  take 120 seconds before it's retried, instead of the whole `timeout`.
+- **The `anthropic` and `openai` backends reuse their connections.** One SDK client is shared by
+  every call in the process (`thunc.map`'s threads and agent runs included), instead of a new
+  client, and so a new TCP and TLS handshake, for each call. A new client is made when the API key,
+  the SDK's environment variables (`ANTHROPIC_*`, `OPENAI_*`) or the process change. In a local
+  benchmark with 60 ms of connection setup, 20 calls in a row went from 1.47 s to 68 ms.
+- **Agents on the text protocol can act several times per reply.** On Codex and `protocol="text"`
+  (and on Claude Code when it falls back to the text protocol), a reply can be a JSON array of
+  independent actions (reading three files) instead of one. They run in order, at most 16 per reply,
+  and every result comes back together, as with native tool calls. Each turn resends the whole
+  transcript and, on the CLI backends, starts the CLI, so fewer turns save both. A single JSON
+  action works as before. On Codex, with `live_tests/eval_prompts.py` (default prompt, 5 runs of
+  each task), every run batched its first reads: replies went from 6.0 / 4.8 / 5.0 to 5.0 / 3.0 /
+  3.6 (fix / review / analysis) and the mean time from 37 / 27 / 27 s to 29 / 19 / 21 s, with the
+  same work done and 30/30 passing.
+- **The `codex` backend returns as soon as the answer arrives.** It reads Codex's JSON events as
+  they come (`codex exec --json`) instead of waiting for the process to exit and reading the answer
+  from a file. Codex takes about 0.4 s to shut down after answering; that now happens in the
+  background. Over 8 alternating pairs of real calls the new way was faster every time, by a median
+  of 0.67 s on a call of about 4 s. Every agent turn on Codex is one call, so the saving repeats.
+
+## 0.2.1 (beta)
+
+**Durable agents with Temporal.** An optional `thunc[temporal]` runtime records each model turn
+and tool call in a Temporal workflow, so a run survives worker restarts and can be reattached
+from another process. Local thunc stays dependency-free. See the
+[Temporal guide](https://github.com/Eltarras/thunc/blob/main/examples/temporal/README.md).
+
+### Added
+
+- **`thunc.temporal`**: `Registry`, `Worker`, `Runtime` and `Handle` to register versioned tasks
+  and start, reattach to, inspect, cancel and resolve durable runs. One coordinator per
+  workspace runs requests in order; a repeated request ID reattaches to the same run. Agents
+  with `tools=` or `timeout=` can't be registered for durable runs yet
+  ([#37](https://github.com/Eltarras/thunc/pull/37)).
+- **Recoverable tool effects**: file writes and memory notes go through an intent and receipt
+  journal with atomic replacement and content hashes. A command whose outcome is uncertain is
+  never rerun automatically: the run waits for an operator's `resolve()`
+  ([#37](https://github.com/Eltarras/thunc/pull/37)).
+- **`thunc.temporal.adapters.execute_task`** composes registered tasks from native Temporal
+  workflows, with a classify → agent analysis → typed summary example
+  ([#38](https://github.com/Eltarras/thunc/pull/38)).
+
+### Changed
+
+- The agent loop's decisions moved into a shared engine (`thunc/execution.py`) that local and
+  durable runs both use. A `remember` call that fails no longer appears in `Run.notes`
+  ([#36](https://github.com/Eltarras/thunc/pull/36)).
+
+## 0.2.0 (beta)
+
+**Agents.** An agent is a typed function that can look around before it answers: it lists,
+reads and searches files in a working directory, and, when its permissions allow, writes, edits
+and runs commands, then returns a checked value of the task's return type.
+See the [Agents section](https://github.com/Eltarras/thunc#agents) of the README.
+
+### Added
+
+- **`thunc.Agent(name, workdir=...)` and `@agent.task`**: declare tasks like `@thunc.function`.
+  Read-only by default, with `list`, `read`, `search` and `remember` tools. Sync and async tasks
+  ([#23](https://github.com/Eltarras/thunc/pull/23)).
+- **Memory and run files** in `.thunc_agents/<name>/`: `memory.md` (notes kept between runs),
+  `agent.json`, and one JSONL record per run. Runs of one agent take turns through an OS file
+  lock ([#23](https://github.com/Eltarras/thunc/pull/23)).
+- **Permission rules**: `write:`, `read:`, `run:` and `!` denies with globs, plus the `write` and
+  `edit` tools. Edits need a fresh read of the file in the same run
+  ([#26](https://github.com/Eltarras/thunc/pull/26)).
+- **The `run` tool**: commands allowed by `run:` rules run without a shell, with a minimal
+  environment and a time limit that also stops their child processes
+  ([#28](https://github.com/Eltarras/thunc/pull/28)).
+- **`agent.run(task, ...)`** returns a `thunc.Run` with the value, files changed, commands,
+  denials, notes and steps. A failed run raises `thunc.AgentError` with the partial record
+  ([#29](https://github.com/Eltarras/thunc/pull/29)).
+- **`follow=`** gives the agent `AGENTS.md` / `CLAUDE.md`, or files you name, as instructions.
+  Off by default ([#31](https://github.com/Eltarras/thunc/pull/31)).
+- **Native tool calls** on the Claude and OpenAI APIs, with the fixed part of the prompt cached.
+  Claude Code and Codex use a JSON text protocol; `protocol="text"` picks it on an API too
+  ([#32](https://github.com/Eltarras/thunc/pull/32)).
+- **System prompt presets**: `thunc.prompts.CODING`, `CODE_REVIEW` and `ANALYSIS`, for `system=`
+  ([#34](https://github.com/Eltarras/thunc/pull/34)).
+- **`tools=`**: your own typed, documented Python functions as agent tools
+  ([#34](https://github.com/Eltarras/thunc/pull/34)).
+- **`agent.call(...)`**, the agent version of `thunc.call`, and the **`@thunc.agent(...)`**
+  shorthand for a one-task agent ([#34](https://github.com/Eltarras/thunc/pull/34)).
+- **`timeout=`** bounds a run's time; command limits are cut to the time left
+  ([#34](https://github.com/Eltarras/thunc/pull/34)).
+- **Files changed by commands** are included in `Run.files_changed`
+  ([#34](https://github.com/Eltarras/thunc/pull/34)).
+- `live_tests/eval_prompts.py`, an evaluation of the agent system prompt (bare / default /
+  preset). 90/90 runs passed on the Claude API and Claude Code
+  ([#34](https://github.com/Eltarras/thunc/pull/34)).
+- CI now also runs the offline tests on Windows ([#34](https://github.com/Eltarras/thunc/pull/34)).
+
+### Changed
+
+- **`thunc.agent` is the decorator** for one-task agents. `from thunc.agent import Agent` still
+  works; only `import thunc.agent as m` now gives the decorator rather than the module.
+- The `codex` backend leaves out Codex's own permission notes, which made it refuse allowed edits
+  ([#26](https://github.com/Eltarras/thunc/pull/26)).
+- Agents refuse the `jev` backend with a `ThuncError` before a run starts; it only answers typed
+  questions ([#33](https://github.com/Eltarras/thunc/pull/33)).
+
+Nothing changes for `@thunc.function` and `thunc.call`.
+
+## 0.1.3 (beta)
+
+- **`jev` backend** for TypeSafe's Jev judgment model: `bool` and `Literal` answers in about
+  0.3 s ([#27](https://github.com/Eltarras/thunc/pull/27)).
+- The **`codex` backend** runs with Codex's own tools off and ignores `~/.codex/config.toml`
+  ([#25](https://github.com/Eltarras/thunc/pull/25)).
+- `@thunc.function` bodies like `return 1` now raise `TypeError` at definition
+  ([#24](https://github.com/Eltarras/thunc/pull/24)).
+
+## 0.1.2 (beta)
+
+- **`cache=True`** saves valid answers on disk; `thunc.clear_cache()`, `thunc.cache_info()` and
+  the `thunc cache` command manage them ([#18](https://github.com/Eltarras/thunc/pull/18),
+  [#19](https://github.com/Eltarras/thunc/pull/19)).
+- **`system=`** replaces the opening of the default system prompt; Codex gets it as its
+  instructions file ([#21](https://github.com/Eltarras/thunc/pull/21)).
+- **Sturdier parsing**: common near-misses are read, and wrong values are retried instead of
+  returned. Only `ThuncError` escapes ([#20](https://github.com/Eltarras/thunc/pull/20)).
+- An empty reply is no longer a valid `str`.
+
+## 0.1.1 (beta)
+
+- **`openai` backend** on the Responses API, and local models through `OPENAI_BASE_URL`.
+- The Claude API backend tested live; CONTRIBUTING.md and Discussions added.
+
+## 0.1.0 (beta)
+
+- First release: `@thunc.function`, `thunc.call`, typed and validated results with retries and
+  `ensure=`, `thunc.map`, JSONL tracing; the `anthropic`, `claude-code` and `codex` backends.

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

@@ -16,34 +16,59 @@ Thanks for helping. thunc is in beta, so feedback on the API is as useful as cod
 
 ```bash
 git clone https://github.com/Eltarras/thunc && cd thunc
-python3 -m venv .venv && .venv/bin/pip install -e ".[anthropic,openai,dev]"
+python3 -m venv .venv && .venv/bin/pip install -e ".[anthropic,openai,temporal-test,dev]"
 ```
 
-The README's [Development](README.md#development) section lists the commands for tests and checks.
+`temporal-test` installs the pinned Temporal SDK the durable-run tests use. Without it the tests in
+`tests/temporal/` are skipped and everything else still runs. The README's
+[Development](README.md#development) section lists the commands for live tests.
 
 ## Before you open a PR
 
-CI runs these on Python 3.10 to 3.14, and all must pass:
+CI runs these on Python 3.10 to 3.14 on Linux, and all must pass. Run each on its own and check
+its exit code:
 
 ```bash
 .venv/bin/pytest
-.venv/bin/ruff check . && .venv/bin/ruff format --check .
+.venv/bin/ruff check .
+.venv/bin/ruff format --check .
 .venv/bin/mypy --strict thunc
+.venv/bin/mypy --strict --platform win32 thunc
+```
+
+CI also runs the offline tests on Windows (Python 3.13), since the agent lock, command handling and
+paths have Windows-only code. If you touch `thunc/temporal/`, run the integration tests against a
+real local Temporal service too (they download it once and make no model calls):
+
+```bash
+THUNC_TEMPORAL_TESTS=1 .venv/bin/pytest -c pytest-temporal.ini tests/temporal
 ```
 
 ## Ground rules
 
 - **Standard library only in the core.** A provider SDK is an optional extra in `pyproject.toml`,
-  imported inside its backend function, never at module level.
+  imported inside its backend function, never at module level. The same goes for Temporal:
+  only `thunc/temporal/` imports `temporalio`, and `thunc.call`, `@thunc.function` and
+  `agent.run()` must keep working without it.
 - **Tests in `tests/` never call a real model.** Use the `fake` fixture in `tests/conftest.py`,
-  which returns scripted replies and records the prompts. Real calls belong in `live_tests/`,
-  which CI doesn't run.
+  which returns scripted replies and records the prompts. Tests of native tool calls replace only
+  the SDK client and use the SDK's real types. Real calls belong in `live_tests/`, which CI
+  doesn't run.
+- **Agent permissions are a safety boundary.** A change to `permissions.py`, `tools.py` or the
+  effect journal in `thunc/temporal/effects.py` needs a test that fails when the rule is broken.
+  Check it by breaking the rule on purpose and watching the test fail.
+- **Durable runs replay.** Workflow code in `thunc/temporal/workflows.py` stays deterministic;
+  model calls, tools and file access happen in activities. A file or memory change goes through
+  the intent and receipt journal, and a command whose outcome is uncertain is never rerun
+  automatically. Before changing orchestration or the saved state format, version it and replay
+  saved histories (see the [Temporal guide](examples/temporal/README.md)).
 - **User data stays out of the instructions.** Inputs are sent separately from the prompt
   (see `_build_prompt` in `thunc/core.py`). Don't add code paths that paste inputs into
   instructions.
 - **Failures are loud.** When no valid answer arrives, raise `ThuncError`; never return a
   default value.
-- **Update the README** when you change the public API or the supported return types.
+- **Update the README** when you change the public API or the supported return types, and the
+  [Temporal guide](examples/temporal/README.md) when you change durable runs.
 - **One change per PR**, with a description of what it does and how you tested it.
 
 ## Adding a backend
@@ -58,7 +83,14 @@ CI runs these on Python 3.10 to 3.14, and all must pass:
    `thunc/config.py` if needed.
 3. Add an optional extra for its SDK in `pyproject.toml`, and add the extra to the CI install.
 4. Add offline tests with a stubbed SDK module, like the existing ones in `tests/test_backends.py`.
-5. Run `THUNC_BACKEND=<name> .venv/bin/pytest live_tests` against the real service, and say in
+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`).
+   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
    the PR that you did.
 
 ## Known issues
@@ -73,8 +105,7 @@ model is asked again instead of thunc guessing:
 - Quoted numbers (`"4"` for an `int`), labels in the wrong case (`Bug` for `bug`), prose around
   JSON, Python-style values (`['a']`, `None`), trailing commas, curly quotes, non-ASCII digits.
 - Unquoted text for `str | None`, and exclamations like `Yes!` for a `bool`.
-- Several `<think>` blocks in a row, several lines of prose before a fence, `~~~`, indented or
-  four-backtick fences.
+- Several `<think>` blocks in a row, `~~~`, indented or four-backtick fences.
 - A one-key object whose key is a field of the expected dataclass: `{"customer": {...}}` for an
   `Order` with a `customer` field is an `Order` with a bad customer, not a wrapper.
 - A reply after the closing fence (for example a reasoning paragraph): it could be a second answer.
@@ -86,7 +117,11 @@ no reliable way to tell them from a real one. Only an empty reply is retried.
 **Open: behavior that might change.**
 
 - `thunc.map` loses every result when one item fails, and returns coroutines for `async` functions.
-- Backend errors (timeouts, connection failures) are never retried; only bad replies are.
+- Backend errors (timeouts, connection failures) are never retried by `thunc.call`; only bad
+  replies are. Local agent runs retry a step that failed with a `TransientError` twice, and durable
+  runs retry transient provider failures.
+- Several lines of prose before a code fence are read as a preamble, though `_unfence` in
+  `thunc/schema.py` documents one line, and no test pins either behavior.
 - A union takes the first option that accepts the reply as JSON, in the order written: `3` for
   `float | int` is `3.0`. An unquoted label is only tried after that, so `2` for
   `Literal["2"] | int` is the int `2`, not the label.
@@ -109,10 +144,38 @@ no reliable way to tell them from a real one. Only an empty reply is retried.
 - A list of dataclasses passed as an input is shown to the model as Python reprs, not JSON.
 - A string return annotation naming a class defined after the function raises `NameError` when
   the decorator runs.
-- `make_dataclass` classes, and `Annotated` fields on Python 3.10, aren't supported.
+- On Python 3.10 and 3.11, a `make_dataclass` class whose field types are strings naming anything
+  but builtins (`"Item"`, `"Annotated[int, 'x']"`) raises `NameError`: before 3.12 its module is
+  `types`, not the caller's.
+- `Annotated[...]` works on dataclass fields but not as a return type.
 - The Python 3.10 fallback for string annotations (`_hints` and `resolve_strings` in
   `thunc/schema.py`) can be removed when 3.10 support is dropped.
 
+**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.
+- 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.
+- A durable workspace can only restart on the same volume and absolute paths; nothing moves it
+  between hosts.
+- A hard worker kill can leave a command's subprocesses running.
+- Durable runs aren't tested on Windows (the code is only type-checked for it), and there are no
+  live provider tests for durable runs yet.
+
 ## Reporting bugs
 
 Open an [issue](https://github.com/Eltarras/thunc/issues) with: