AgentX-Dev 3.8.1__tar.gz → 3.9.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (141) hide show
  1. {agentx_dev-3.8.1 → agentx_dev-3.9.0}/CHANGELOG.md +1649 -1588
  2. {agentx_dev-3.8.1 → agentx_dev-3.9.0}/PKG-INFO +10 -1
  3. {agentx_dev-3.8.1 → agentx_dev-3.9.0}/README.md +1436 -1428
  4. {agentx_dev-3.8.1 → agentx_dev-3.9.0}/agentx_dev/ChatModel.py +7 -1
  5. {agentx_dev-3.8.1 → agentx_dev-3.9.0}/agentx_dev/Session.py +54 -11
  6. {agentx_dev-3.8.1 → agentx_dev-3.9.0}/agentx_dev/cli/app.py +18 -5
  7. agentx_dev-3.9.0/agentx_dev/cli/app_keys.py +118 -0
  8. agentx_dev-3.9.0/agentx_dev/cli/keystore.py +99 -0
  9. {agentx_dev-3.8.1 → agentx_dev-3.9.0}/agentx_dev/cli/team_record.py +82 -4
  10. {agentx_dev-3.8.1 → agentx_dev-3.9.0}/agentx_dev/cli/webui.py +243 -5
  11. {agentx_dev-3.8.1 → agentx_dev-3.9.0}/agentx_dev/resources/webui/app.js +1741 -1386
  12. {agentx_dev-3.8.1 → agentx_dev-3.9.0}/agentx_dev/resources/webui/index.html +165 -135
  13. agentx_dev-3.9.0/agentx_dev/resources/webui/orb.js +272 -0
  14. {agentx_dev-3.8.1 → agentx_dev-3.9.0}/agentx_dev/resources/webui/style.css +677 -535
  15. {agentx_dev-3.8.1 → agentx_dev-3.9.0}/agentx_dev.egg-info/PKG-INFO +10 -1
  16. {agentx_dev-3.8.1 → agentx_dev-3.9.0}/agentx_dev.egg-info/SOURCES.txt +3 -0
  17. {agentx_dev-3.8.1 → agentx_dev-3.9.0}/agentx_dev.egg-info/requires.txt +1 -0
  18. {agentx_dev-3.8.1 → agentx_dev-3.9.0}/pyproject.toml +101 -100
  19. {agentx_dev-3.8.1 → agentx_dev-3.9.0}/AGENTX.md +0 -0
  20. {agentx_dev-3.8.1 → agentx_dev-3.9.0}/CONTRIBUTING.md +0 -0
  21. {agentx_dev-3.8.1 → agentx_dev-3.9.0}/LICENSE +0 -0
  22. {agentx_dev-3.8.1 → agentx_dev-3.9.0}/MANIFEST.in +0 -0
  23. {agentx_dev-3.8.1 → agentx_dev-3.9.0}/agentx_dev/Agents/Agent.py +0 -0
  24. {agentx_dev-3.8.1 → agentx_dev-3.9.0}/agentx_dev/Agents/__init__.py +0 -0
  25. {agentx_dev-3.8.1 → agentx_dev-3.9.0}/agentx_dev/AsyncTools.py +0 -0
  26. {agentx_dev-3.8.1 → agentx_dev-3.9.0}/agentx_dev/AutoSetup.py +0 -0
  27. {agentx_dev-3.8.1 → agentx_dev-3.9.0}/agentx_dev/Cache.py +0 -0
  28. {agentx_dev-3.8.1 → agentx_dev-3.9.0}/agentx_dev/Compiler.py +0 -0
  29. {agentx_dev-3.8.1 → agentx_dev-3.9.0}/agentx_dev/Config.py +0 -0
  30. {agentx_dev-3.8.1 → agentx_dev-3.9.0}/agentx_dev/DefaultTools.py +0 -0
  31. {agentx_dev-3.8.1 → agentx_dev-3.9.0}/agentx_dev/Embeddings.py +0 -0
  32. {agentx_dev-3.8.1 → agentx_dev-3.9.0}/agentx_dev/Evals.py +0 -0
  33. {agentx_dev-3.8.1 → agentx_dev-3.9.0}/agentx_dev/Handoffs.py +0 -0
  34. {agentx_dev-3.8.1 → agentx_dev-3.9.0}/agentx_dev/Loader.py +0 -0
  35. {agentx_dev-3.8.1 → agentx_dev-3.9.0}/agentx_dev/MCP.py +0 -0
  36. {agentx_dev-3.8.1 → agentx_dev-3.9.0}/agentx_dev/Media.py +0 -0
  37. {agentx_dev-3.8.1 → agentx_dev-3.9.0}/agentx_dev/Memory.py +0 -0
  38. {agentx_dev-3.8.1 → agentx_dev-3.9.0}/agentx_dev/Observability.py +0 -0
  39. {agentx_dev-3.8.1 → agentx_dev-3.9.0}/agentx_dev/Operator.py +0 -0
  40. {agentx_dev-3.8.1 → agentx_dev-3.9.0}/agentx_dev/Pictures.py +0 -0
  41. {agentx_dev-3.8.1 → agentx_dev-3.9.0}/agentx_dev/Planner.py +0 -0
  42. {agentx_dev-3.8.1 → agentx_dev-3.9.0}/agentx_dev/RunLog.py +0 -0
  43. {agentx_dev-3.8.1 → agentx_dev-3.9.0}/agentx_dev/Runner/AgentRun.py +0 -0
  44. {agentx_dev-3.8.1 → agentx_dev-3.9.0}/agentx_dev/Runner/AsyncAgentRun.py +0 -0
  45. {agentx_dev-3.8.1 → agentx_dev-3.9.0}/agentx_dev/Runner/Persistence.py +0 -0
  46. {agentx_dev-3.8.1 → agentx_dev-3.9.0}/agentx_dev/Runner/Trim.py +0 -0
  47. {agentx_dev-3.8.1 → agentx_dev-3.9.0}/agentx_dev/Runner/__init__.py +0 -0
  48. {agentx_dev-3.8.1 → agentx_dev-3.9.0}/agentx_dev/Runner/promptTemplate.yaml +0 -0
  49. {agentx_dev-3.8.1 → agentx_dev-3.9.0}/agentx_dev/Skills/Attach.py +0 -0
  50. {agentx_dev-3.8.1 → agentx_dev-3.9.0}/agentx_dev/Skills/Defaults.py +0 -0
  51. {agentx_dev-3.8.1 → agentx_dev-3.9.0}/agentx_dev/Skills/Install.py +0 -0
  52. {agentx_dev-3.8.1 → agentx_dev-3.9.0}/agentx_dev/Skills/Store.py +0 -0
  53. {agentx_dev-3.8.1 → agentx_dev-3.9.0}/agentx_dev/Skills/__init__.py +0 -0
  54. {agentx_dev-3.8.1 → agentx_dev-3.9.0}/agentx_dev/Splitters.py +0 -0
  55. {agentx_dev-3.8.1 → agentx_dev-3.9.0}/agentx_dev/Streaming.py +0 -0
  56. {agentx_dev-3.8.1 → agentx_dev-3.9.0}/agentx_dev/SubAgents.py +0 -0
  57. {agentx_dev-3.8.1 → agentx_dev-3.9.0}/agentx_dev/Supervisor.py +0 -0
  58. {agentx_dev-3.8.1 → agentx_dev-3.9.0}/agentx_dev/SupervisorMemory.py +0 -0
  59. {agentx_dev-3.8.1 → agentx_dev-3.9.0}/agentx_dev/Tools.py +0 -0
  60. {agentx_dev-3.8.1 → agentx_dev-3.9.0}/agentx_dev/VectorStores/__init__.py +0 -0
  61. {agentx_dev-3.8.1 → agentx_dev-3.9.0}/agentx_dev/VectorStores/chroma_store.py +0 -0
  62. {agentx_dev-3.8.1 → agentx_dev-3.9.0}/agentx_dev/VectorStores/pg_store.py +0 -0
  63. {agentx_dev-3.8.1 → agentx_dev-3.9.0}/agentx_dev/VectorStores/qdrant_store.py +0 -0
  64. {agentx_dev-3.8.1 → agentx_dev-3.9.0}/agentx_dev/WebTools.py +0 -0
  65. {agentx_dev-3.8.1 → agentx_dev-3.9.0}/agentx_dev/__init__.py +0 -0
  66. {agentx_dev-3.8.1 → agentx_dev-3.9.0}/agentx_dev/__main__.py +0 -0
  67. {agentx_dev-3.8.1 → agentx_dev-3.9.0}/agentx_dev/_optional.py +0 -0
  68. {agentx_dev-3.8.1 → agentx_dev-3.9.0}/agentx_dev/_supervisor/__init__.py +0 -0
  69. {agentx_dev-3.8.1 → agentx_dev-3.9.0}/agentx_dev/_supervisor/core.py +0 -0
  70. {agentx_dev-3.8.1 → agentx_dev-3.9.0}/agentx_dev/_supervisor/plans.py +0 -0
  71. {agentx_dev-3.8.1 → agentx_dev-3.9.0}/agentx_dev/_supervisor/prompts.py +0 -0
  72. {agentx_dev-3.8.1 → agentx_dev-3.9.0}/agentx_dev/_supervisor/results.py +0 -0
  73. {agentx_dev-3.8.1 → agentx_dev-3.9.0}/agentx_dev/_supervisor/steps.py +0 -0
  74. {agentx_dev-3.8.1 → agentx_dev-3.9.0}/agentx_dev/cli/__init__.py +0 -0
  75. {agentx_dev-3.8.1 → agentx_dev-3.9.0}/agentx_dev/cli/app_mcp.py +0 -0
  76. {agentx_dev-3.8.1 → agentx_dev-3.9.0}/agentx_dev/cli/app_models.py +0 -0
  77. {agentx_dev-3.8.1 → agentx_dev-3.9.0}/agentx_dev/cli/app_team.py +0 -0
  78. {agentx_dev-3.8.1 → agentx_dev-3.9.0}/agentx_dev/cli/app_usage.py +0 -0
  79. {agentx_dev-3.8.1 → agentx_dev-3.9.0}/agentx_dev/cli/app_voice.py +0 -0
  80. {agentx_dev-3.8.1 → agentx_dev-3.9.0}/agentx_dev/cli/approval.py +0 -0
  81. {agentx_dev-3.8.1 → agentx_dev-3.9.0}/agentx_dev/cli/commands.py +0 -0
  82. {agentx_dev-3.8.1 → agentx_dev-3.9.0}/agentx_dev/cli/compact.py +0 -0
  83. {agentx_dev-3.8.1 → agentx_dev-3.9.0}/agentx_dev/cli/context.py +0 -0
  84. {agentx_dev-3.8.1 → agentx_dev-3.9.0}/agentx_dev/cli/fullscreen.py +0 -0
  85. {agentx_dev-3.8.1 → agentx_dev-3.9.0}/agentx_dev/cli/mcp.py +0 -0
  86. {agentx_dev-3.8.1 → agentx_dev-3.9.0}/agentx_dev/cli/memory.py +0 -0
  87. {agentx_dev-3.8.1 → agentx_dev-3.9.0}/agentx_dev/cli/models.py +0 -0
  88. {agentx_dev-3.8.1 → agentx_dev-3.9.0}/agentx_dev/cli/preview.py +0 -0
  89. {agentx_dev-3.8.1 → agentx_dev-3.9.0}/agentx_dev/cli/recall.py +0 -0
  90. {agentx_dev-3.8.1 → agentx_dev-3.9.0}/agentx_dev/cli/remote.py +0 -0
  91. {agentx_dev-3.8.1 → agentx_dev-3.9.0}/agentx_dev/cli/safepaths.py +0 -0
  92. {agentx_dev-3.8.1 → agentx_dev-3.9.0}/agentx_dev/cli/sessions.py +0 -0
  93. {agentx_dev-3.8.1 → agentx_dev-3.9.0}/agentx_dev/cli/settings.py +0 -0
  94. {agentx_dev-3.8.1 → agentx_dev-3.9.0}/agentx_dev/cli/team.py +0 -0
  95. {agentx_dev-3.8.1 → agentx_dev-3.9.0}/agentx_dev/cli/tools.py +0 -0
  96. {agentx_dev-3.8.1 → agentx_dev-3.9.0}/agentx_dev/cli/trust.py +0 -0
  97. {agentx_dev-3.8.1 → agentx_dev-3.9.0}/agentx_dev/cli/typeahead.py +0 -0
  98. {agentx_dev-3.8.1 → agentx_dev-3.9.0}/agentx_dev/cli/ui.py +0 -0
  99. {agentx_dev-3.8.1 → agentx_dev-3.9.0}/agentx_dev/cli/ui_input.py +0 -0
  100. {agentx_dev-3.8.1 → agentx_dev-3.9.0}/agentx_dev/cli/ui_text.py +0 -0
  101. {agentx_dev-3.8.1 → agentx_dev-3.9.0}/agentx_dev/cli/voice.py +0 -0
  102. {agentx_dev-3.8.1 → agentx_dev-3.9.0}/agentx_dev/resources/__init__.py +0 -0
  103. {agentx_dev-3.8.1 → agentx_dev-3.9.0}/agentx_dev/resources/promptTemplate.yaml +0 -0
  104. {agentx_dev-3.8.1 → agentx_dev-3.9.0}/agentx_dev/resources/skills/auditing-a-project/SKILL.md +0 -0
  105. {agentx_dev-3.8.1 → agentx_dev-3.9.0}/agentx_dev/resources/skills/changing-files/SKILL.md +0 -0
  106. {agentx_dev-3.8.1 → agentx_dev-3.9.0}/agentx_dev/resources/skills/delegating-work/SKILL.md +0 -0
  107. {agentx_dev-3.8.1 → agentx_dev-3.9.0}/agentx_dev/resources/skills/exploring-a-project/SKILL.md +0 -0
  108. {agentx_dev-3.8.1 → agentx_dev-3.9.0}/agentx_dev/resources/skills/running-code/SKILL.md +0 -0
  109. {agentx_dev-3.8.1 → agentx_dev-3.9.0}/agentx_dev/resources/skills/web-research/SKILL.md +0 -0
  110. {agentx_dev-3.8.1 → agentx_dev-3.9.0}/agentx_dev/resources/webui/icon.svg +0 -0
  111. {agentx_dev-3.8.1 → agentx_dev-3.9.0}/agentx_dev/safe_exe.py +0 -0
  112. {agentx_dev-3.8.1 → agentx_dev-3.9.0}/agentx_dev.egg-info/dependency_links.txt +0 -0
  113. {agentx_dev-3.8.1 → agentx_dev-3.9.0}/agentx_dev.egg-info/entry_points.txt +0 -0
  114. {agentx_dev-3.8.1 → agentx_dev-3.9.0}/agentx_dev.egg-info/top_level.txt +0 -0
  115. {agentx_dev-3.8.1 → agentx_dev-3.9.0}/examples/README.md +0 -0
  116. {agentx_dev-3.8.1 → agentx_dev-3.9.0}/examples/agentic_rag_demo.py +0 -0
  117. {agentx_dev-3.8.1 → agentx_dev-3.9.0}/examples/async_example.py +0 -0
  118. {agentx_dev-3.8.1 → agentx_dev-3.9.0}/examples/async_quickstart.py +0 -0
  119. {agentx_dev-3.8.1 → agentx_dev-3.9.0}/examples/auto_features_example.py +0 -0
  120. {agentx_dev-3.8.1 → agentx_dev-3.9.0}/examples/caching_example.py +0 -0
  121. {agentx_dev-3.8.1 → agentx_dev-3.9.0}/examples/chatbot_example.py +0 -0
  122. {agentx_dev-3.8.1 → agentx_dev-3.9.0}/examples/complete_example.py +0 -0
  123. {agentx_dev-3.8.1 → agentx_dev-3.9.0}/examples/concurrent_example.py +0 -0
  124. {agentx_dev-3.8.1 → agentx_dev-3.9.0}/examples/concurrent_tool_example.py +0 -0
  125. {agentx_dev-3.8.1 → agentx_dev-3.9.0}/examples/file_agent_demo.py +0 -0
  126. {agentx_dev-3.8.1 → agentx_dev-3.9.0}/examples/function_calling_demo.py +0 -0
  127. {agentx_dev-3.8.1 → agentx_dev-3.9.0}/examples/mcp_demo.py +0 -0
  128. {agentx_dev-3.8.1 → agentx_dev-3.9.0}/examples/mcp_github_triage_demo.py +0 -0
  129. {agentx_dev-3.8.1 → agentx_dev-3.9.0}/examples/observability_example.py +0 -0
  130. {agentx_dev-3.8.1 → agentx_dev-3.9.0}/examples/orchestration_demo.py +0 -0
  131. {agentx_dev-3.8.1 → agentx_dev-3.9.0}/examples/planner_example.py +0 -0
  132. {agentx_dev-3.8.1 → agentx_dev-3.9.0}/examples/robust_link_scraper.py +0 -0
  133. {agentx_dev-3.8.1 → agentx_dev-3.9.0}/examples/subagents_demo.py +0 -0
  134. {agentx_dev-3.8.1 → agentx_dev-3.9.0}/examples/supervisor_codebase_analysis_demo.py +0 -0
  135. {agentx_dev-3.8.1 → agentx_dev-3.9.0}/examples/supervisor_example.py +0 -0
  136. {agentx_dev-3.8.1 → agentx_dev-3.9.0}/examples/sync_quickstart.py +0 -0
  137. {agentx_dev-3.8.1 → agentx_dev-3.9.0}/examples/v3_1_1_features_demo.py +0 -0
  138. {agentx_dev-3.8.1 → agentx_dev-3.9.0}/examples/v3_1_comprehensive_demo.py +0 -0
  139. {agentx_dev-3.8.1 → agentx_dev-3.9.0}/examples/v3_1_features_demo.py +0 -0
  140. {agentx_dev-3.8.1 → agentx_dev-3.9.0}/host/build_data.py +0 -0
  141. {agentx_dev-3.8.1 → agentx_dev-3.9.0}/setup.cfg +0 -0
@@ -1,1588 +1,1649 @@
1
- # Changelog
2
-
3
- All notable changes to `agentx-dev` are documented here. Format loosely
4
- follows [Keep a Changelog](https://keepachangelog.com/); versioning is
5
- [Semver](https://semver.org/).
6
-
7
- ## [Unreleased]
8
-
9
- ## [3.8.1] - 2026-11-13
10
-
11
- ### Changed
12
-
13
- - **The app window opens like the docs site.** The mark rises with a soft glow, `agentx` types itself in letter by
14
- letter and a lime cursor keeps blinking after it; "Starting..." (dots lighting up in turn) shows until agentx is
15
- ready, and the welcome grows out of it. While it works, that blinking cursor replaces the round spinner.
16
- - **The folder trust question highlights "No, exit".** Enter alone now exits; trust a folder with `1`, `y`, or Up
17
- then Enter. The app window's trust card does the same.
18
- - **"Don't ask again" is `2` in approval menus.** The `a` shortcut is gone from the arrow-key menu (it still works in
19
- the typed `[y/a/n]` prompt), so a word typed for the chat cannot pick it.
20
- - **Menus wait a moment before they take keys.** Keys typed before a menu appeared are thrown away, and keys pressed
21
- in its first 0.4 seconds are ignored (Ctrl+C still cancels). In full-screen mode a menu waits while the input line
22
- holds text (`Clear or send your message to answer`); keys keep editing the message and Enter sends it.
23
- - **App window cards do not take the focus while you type.** When the message box holds text, or another field has
24
- the focus, a new card leaves the focus where it is; from an empty message box `1`, `2`, `3` answer it but Enter and
25
- Space do not.
26
- - **Some granted commands ask again.** A "don't ask again" command grant no longer covers a call that uses an option
27
- through which the program runs another program (`git fetch --upload-pack`, `make -f`, `rg --pre` and similar), and
28
- `find`, `sed`, `tar`, `rsync`, `vim`, `git submodule`, `git rebase` and similar are never remembered.
29
- - **An MCP server launcher that exists only as a `.ps1` script needs its full path.** A bare `"command"` is now looked
30
- up on `PATH` only; one not found reads `not connected: <name> not found on PATH`.
31
- - **A parent folder's `AGENTX.md` needs that folder trusted.** To use a repository's top-level file when you start
32
- in a subfolder, trust the top folder once.
33
-
34
- ### Fixed
35
-
36
- - **`--remote` on a VPS prints the ssh command that works.** It assumed SSH on port 22 and guessed the address, so
37
- a server on another port (2222, say) timed out. In an SSH session agentx now uses the address and port that
38
- session came in on (`ssh -p 2222 ...`).
39
-
40
- ### Security
41
-
42
- - **Keys typed for the chat never answer an approval.** Keys still waiting when a prompt opens go to your message
43
- line, never to the prompt; menus throw away keys typed before they appeared and ignore the first 0.4 seconds.
44
- - **A stray Enter never trusts a folder.** The trust question opens on "No, exit", and keys typed while agentx
45
- started are thrown away.
46
- - **A command grant cannot approve another program.** "Don't ask again" on a command no longer approves a later call
47
- that runs another program through its options (`git fetch --upload-pack`, `git grep -O`, `git -c`, `make -f` or
48
- `VAR=value`, `go test -exec`, `cargo --config`, `rg --pre`, `npm --script-shell`) or holds `$ * ? [ {` for such a
49
- program. Programs that run others through their options or scripts (`find`, `sed`, `tar`, `rsync`, `scp`, `zip`,
50
- `vim`, `parallel`, `crontab`, `at`...) and git sub-commands such as `submodule`, `rebase`, `difftool`, `config` and
51
- `hook` are approved once and never remembered.
52
- - **An edit grant covers edits only.** Answering "don't ask again" at an edit prompt no longer lets web searches and
53
- page fetches run unasked; they still ask until you choose `accept-edits` yourself or allow the web at a web prompt.
54
- - **`/clear` and `/resume` also end a web "don't ask again" grant.**
55
- - **The approval diff shows every hidden line break.** Lines split at LF only: a line break swapped for a form feed,
56
- a vertical tab, U+2028 or a lone CR shows as a changed line with an escape such as `\x0c`, not as "only line
57
- endings change".
58
- - **Backslash paths on Linux and macOS.** A backslash is part of a file name there, so the deny rules (and the
59
- prompt) also judge the file the name really reaches: a link named `x\y` cannot lead past the `.git` protection.
60
- - **The window's key is never on a command line.** The window agentx opens gets a one-time start link (`?c=`) that
61
- works once, for 2 minutes; the page trades it for the key. A second use is refused, the key is changed and the
62
- terminal prints a warning with the new link.
63
- - **An approval too long to show in full is declined.** A card whose action, target or preview would be cut is
64
- declined without asking, with a notice saying why; "don't ask again" is not offered for a rule too long to show.
65
- - **Links in answers cannot add attributes.** A link's address ends at a space, `(`, `)` or a quote, and each link is
66
- built once, so model text cannot break out of it.
67
- - **Saving Settings keeps declined project rules off.** Project allow rules you turned down at start, and rules added
68
- to the project file since, stay off for the session after the window saves the settings.
69
- - **Open another folder imports nothing from that folder** before the new agentx asks whether you trust it.
70
- - **Pictures are never saved through a planted link.** When the project's `.agentx` or `.agentx/uploads` is a link,
71
- a picture goes to `~/.agentx/uploads/`; the message names where the file really is.
72
- - **Turning remote control off closes the windows opened through Tailscale** (their conversations are saved), and
73
- the 30-second re-share check can no longer share the window again afterwards. agentx also changes its key, so a
74
- link shared with another device stops working; windows on this computer get the new key and keep going.
75
- - **Nothing is started from the project folder on Windows.** `run_shell` takes git-bash from Program Files, a
76
- per-user Git install or `PATH` without the current folder, else System32's PowerShell; stopping a command runs
77
- System32's `taskkill`; Tailscale, Edge, Chrome and PowerShell for the app window are found the same way.
78
- - **MCP stdio servers' bare commands are found on `PATH` only**, never in the project folder (the server still
79
- starts in the current folder).
80
- - **Read-only auto-allows are re-checked on every connect.** Tools allowed because the server marked them read-only
81
- are kept in `"auto"` in `mcp.json`, apart from your own `/mcp allow` choices; one the server stops marking read-only
82
- asks again, with a warning. On the first connect after upgrading, saved `"allow"` entries the server marks
83
- read-only move to `"auto"`.
84
- - **A sign-in is tied to the server's address.** When a server's URL changes, the old sign-in is deleted instead of
85
- being sent there; a server taken out of `mcp.json` is disconnected and its sign-in deleted; `/mcp add` under a
86
- name used before starts signed out.
87
- - **A parent folder's `AGENTX.md` is read only when you trust that folder.** The folder you start in and your home
88
- folder's file are always read.
89
- - **`grep` and `find_files` do not follow links out of the project.** A linked file that leads outside is skipped and
90
- linked folders (Windows junctions included) are never entered.
91
- - **`web_fetch` connects only to the address it checked**, on every redirect, so DNS rebinding cannot reach a local
92
- address; a redirect to a private address reads `ERROR: refused`.
93
- - **Saved conversations and their titles are readable by you only** (`0600`, new folders `0700`), and `~/.agentx` is
94
- created yours only.
95
- - **`/skills install` refuses a repository whose skill files have `:` in their paths** (another drive, or an NTFS
96
- stream, on Windows) and never writes outside its download folder.
97
-
98
- ## [3.8.0] - 2026-11-08
99
-
100
- ### Added
101
-
102
- - **One conversation per device in remote use.** Each device that opens the window (an iPad, a laptop, the
103
- computer's own window) gets its own conversation and agent, with its own approvals, Stop and status, working at
104
- the same time as the others in the same folder; before, every window shared one conversation, so a second
105
- device's message slipped into the running task. The computer's conversation (the terminal's, or the first
106
- window's) is listed on the others as **Live** and can be opened to share it, as before. `/exit` on a device ends
107
- only its own; one unused for 15 minutes is put away and reopened when the device comes back; settings saved on
108
- one device reach all; a window says when another conversation is working in the folder. Inside: each
109
- conversation has its own team lane (a team job's questions, notes and `/skip` never reach another's), the
110
- conversation titles, work log and team records take several writers, and one MCP sign-in runs at a time.
111
- - **`agentx --ui`: the app window.** The same agentx in a desktop-style window instead of the terminal: the
112
- conversations of the folder on the left (open one, or start a new one), your messages on the right, the agent's
113
- steps as short rows (Read, Edit, Run, with look-around steps folded into one Explored row), answers rendered as
114
- markdown, approvals as cards with the diff and Yes / don't ask again / No (with a reason) and keys 1-3, the other
115
- questions as cards, the team's running steps, typed messages waiting with a button to take each back, and a
116
- message box with the mode and model menus, `/` for commands and skills, a picture button (and paste or drop;
117
- saved in `.agentx/uploads/`), a microphone button (`/voice`) and a send button that is Stop while it works.
118
- It opens as an Edge or Chrome app window when one is installed, else in the browser. The app itself runs
119
- unchanged; the window is another front end, served on 127.0.0.1 with a random token per start and a Host check.
120
- `--port` and `--no-open`. No new packages.
121
- - **The app window's side panel, Settings and remote use.** **Details** shows how full the conversation is, the
122
- tokens used, the last team job step by step, the MCP servers by name with their own Sign in / Reconnect / Tools /
123
- Sign out buttons, and the project memory. **Settings** saves the default model and mode, the allow and deny rules,
124
- the steps and the token limit, for all folders or this folder (rules and limits apply at once). The **+** menu adds
125
- a picture, mentions a file (search) or opens another folder in a new window. `agentx --ui --remote` keeps the window
126
- on the server's 127.0.0.1 and prints the `ssh -N -L` command to use it from another computer. Light or dark follows
127
- the system. A notice that MCP servers need sign-in has a button per server.
128
- - **Remote control.** `/remote-control` in the terminal makes the running session usable from an iPad, a phone or
129
- another computer: the terminal keeps showing everything, the window mirrors it, and messages, answers, menu choices
130
- and approvals from the window go into the terminal's own prompt (the first answer wins). In the app window it adds
131
- the remote ways to the window already served. With Tailscale on, `--remote` and `/remote-control` also listen on
132
- the computer's Tailscale address (Tailscale devices only) and print a link for Safari; otherwise the SSH way. They
133
- say when no SSH server runs, or when Windows Firewall blocks SSH on a Public network.
134
- - **The model's thinking, shown.** On Claude Opus 5.5, Sonnet 5.5 and Fable 5.1 agentx asks for a readable summary of
135
- the reasoning they do on every step anyway (`thinking.display: "summarized"`, same cost; nothing is sent back on
136
- later requests), and on GPT reasoning models on the Responses API for OpenAI's reasoning summary (asked once more
137
- only if the account allows it). The app window shows it, and the model's notes between steps, as Thinking blocks
138
- as they happen, with a live Thinking… line; the terminal shows it before an edit or a command. In the library:
139
- `Claude(show_reasoning=True)`, `GPT(show_reasoning=True)`, `"reasoning"` in a `call_with_tools` result, and a
140
- `{"type": "reasoning"}` runner event.
141
- - **MCP sign-in from a remote window.** The sign-in page is a card in the window, and pasting the address of the
142
- page that could not load afterwards finishes the sign-in on the agentx computer.
143
- - **Conversation titles and closing the window.** After its first answer, a conversation gets a short title from the
144
- model (one small request, on a thread of its own), shown in the app window's list and in `/resume`; older ones
145
- show the first thing you typed, no longer agentx's summary note. Closing the app window quits agentx (a running turn
146
- stops and is kept, the conversation is saved); a reload does not. Not with `--no-open` or `--remote`.
147
- - **`agentx`: commands while it works, and `/unsend`.** Commands that only show something (`/usage`, `/settings`,
148
- `/help`, `/team log`, `/skills`, `/mcp`, `/memory`, `/sessions`, and `/model`, `/team-models`, `/limit`,
149
- `/fullscreen` with nothing after them) run at once while the agent works, and `/mode` changes the mode at once;
150
- they used to wait (`runs when the agent is done`). `/voice` starts recording at once: Enter stops it and the words
151
- go into the line being typed, to check and send. `/unsend` takes back a waiting message (or a team note) before it
152
- is read: the newest, `/unsend 2`, or `/unsend all`; the waiting lines are numbered. Commands that change the
153
- conversation or the setup still wait. The agent and the team's runner are told not to wait inside a command
154
- (`sleep`, `--watch`): they check CI or a deploy once and report. The zero-to-hero guide has `/init` as step 4.
155
- - **`agentx`: `/voice`.** Records from the default microphone until Enter (Ctrl+C cancels), writes out what was said
156
- with OpenAI's speech-to-text (`gpt-4o-transcribe`, falling back to `whisper-1`; `AGENTX_VOICE_MODEL` picks another)
157
- and puts the words in the next input line to check before sending, in the normal and the full-screen screen.
158
- Claude models take no audio, so it needs `OPENAI_API_KEY` whatever the chat model. The microphone is read with
159
- `sounddevice`: new extra `agentx-dev[voice]`. A recording stops by itself at 10 minutes; a microphone that cannot
160
- record at 16 kHz records at its own rate.
161
- - **Agents can look at pictures.** `read_path` on a PNG, JPEG, GIF or WebP file hands the model the picture itself
162
- (it used to answer `file is not utf-8 text`), so an agent or a team helper that takes a screenshot can see it. It
163
- works on Claude (inside the `tool_result`) and GPT (Chat Completions and Responses: the tool message gets the text,
164
- and a message right after the tool results carries the picture). The type comes from the file's contents; a
165
- picture over 5 MB or 8,000 pixels is made smaller with Pillow when it is installed, and refused otherwise. Each
166
- request carries the newest three pictures from tool results; older ones become a note naming the file (the history
167
- keeps them). Logs, the screen and team summaries show one line (`Picture shot.png: PNG, 1440x900, 245 KB.`); in
168
- `agentx` the tool line reads `Picture, 1440x900`. In `agentx` a picture outside the project folder (a screenshot in the user's Pictures folder) is opened after an approval prompt instead of being refused; other files outside stay refused. The agent and the team planner are told they can do this. New
169
- module `agentx_dev.Pictures` (`picture_result`, `ToolContent`) for tools of your own.
170
- - **`agentx`: type while the agent works.** On the normal screen what you type while the spinner runs shows under it,
171
- and Enter sends it to the agent at its next step, so it can change course without waiting. During a team job a
172
- message goes to the team: running helpers read it at their next step, later steps start with it, and the main
173
- agent reads it in the job's result (to add work). `/skip <step number or helper>` skips a team step not started
174
- yet. Another command typed then runs when the agent is done. A sent message waits under the spinner (`◌ ...`) and,
175
- once read, leaves one line: `❯ text ✓ read by <the agent or the helper>`. The spinner says `type to add to the
176
- task`. Full-screen mode does the same (a message typed
177
- there used to wait for the end of the turn). Approval prompts still get every key.
178
- - **`AgentRunner.interjections` and `AsyncAgentRunner.interjections`.** Set it to a function that returns the messages
179
- a user sent while the run was going; each is added to the run before the next step, and `stream` yields
180
- `{"type": "interjection", "content": ...}` for it.
181
-
182
- - **`log=` on `AgentRunner` and `AsyncAgentRunner`: watch a run as it goes.** `log=True` prints one short line per
183
- step to stderr; a file path appends JSON lines (`.jsonl`) or readable lines; a `logging.Logger` sends them to your
184
- logging setup; a function receives each event. Lines: the start, each model call (time, tokens in, cached and
185
- out), each tool result (ok or error, arguments and result cut short), and the end (outcome and totals) or the
186
- error. Secrets are redacted, and a log that cannot be written never stops the run. New `RunLog` class
187
- (`RunLog.chain` writes to several). See "Watching one runner" in the observability guide.
188
- - **The eval harness catches up.** `EvalRunner` runs an `AsyncAgentRunner`, a `Supervisor` or an `AsyncSupervisor`
189
- as well as an `AgentRunner` (async ones from a notebook too); new checks `outcome_is`, `output_field`,
190
- `used_skill`, `used_agent`, `subtasks_ok` and `EvalCase(max_tool_errors=)`, with the same fields in JSON cases;
191
- `repeat=` runs each case several times (the summary shows `[2/3]`), `tags=` picks cases; results carry
192
- `counted_tokens` (cached input as a tenth), `model_calls` and the failed tools; `compare_reports` and
193
- `python -m agentx_dev.Evals compare a.json b.json` put two reports side by side; the CLI takes `--repeat`,
194
- `--tag` and `--log`.
195
-
196
- - **Public extension points on `Supervisor` and `AsyncSupervisor`:** `prepare_plan(plan)` (change a plan before it
197
- runs), `run_step(agent_name, query, run)` (wrap or skip every step), `spawn_specialist(spec)` (build the helpers a
198
- plan defines your own way) and `planner_note` (text added to the planner's list of specialists). A planned helper's
199
- `new_agent` may name a `model`, kept by the plan checker and passed as `AgentSpec.model`. The `agentx` team runner
200
- now uses only these, no underscore methods. See "Changing how a Supervisor runs" in the sub-agents guide.
201
-
202
- ### Changed
203
-
204
- - **`Claude()` defaults to `claude-opus-5-5` with `max_tokens=16000`** (was `claude-sonnet-4-6`, 4096). Opus 5.5
205
- always thinks and the thinking counts toward the limit, so 4096 could cut answers short. `agentx`'s help text and
206
- hints name `claude-opus-5-5` and `gpt-6.1-sol`. See Upgrading.
207
-
208
- - **`Supervisor` and `AsyncSupervisor` share one core.** Planning, replanning, synthesis, a step's retries and the
209
- rounds of a session are written once (they were two copies that had to be fixed twice). `AsyncSupervisor` awaits
210
- real work; `Supervisor` runs the same code with sync calls, still in your thread, with no event loop, so it keeps
211
- working in a notebook. Each class keeps its own way of running a plan: one step at a time, or side by side. No
212
- change in behaviour: the same events and log lines.
213
-
214
- - **Smaller source files.** `Supervisor.py` (2,900 lines) keeps the two classes; its helpers moved to the private
215
- package `agentx_dev/_supervisor/`. The `agentx` app's `ChatApp` gets its MCP, model, usage and team commands from
216
- four files (`cli/app_mcp.py`, `app_models.py`, `app_usage.py`, `app_team.py`), and `cli/ui.py` its text and input
217
- helpers from `ui_text.py` and `ui_input.py`. Every name is still importable from where it was.
218
-
219
- - **The public API is written down** in `docs/reference/public-api.md`: every name exported from `agentx_dev`, the
220
- stable import paths below it, what is not public (underscore names, the `agentx` command's Python modules), and
221
- how patch, minor and major versions may change it. A test fails when the package and the page disagree.
222
-
223
- - **A smaller base install.** `chromadb`, `qdrant-client`, `psycopg`, `pandas` and `openpyxl` moved from the base
224
- dependencies to extras: `[rag]` (the three vector stores; `[chroma]`, `[qdrant]`, `[pgvector]` one at a time),
225
- `[excel]` (spreadsheets in `Media`), `[all]`. A missing package's error names the extra. See Upgrading.
226
-
227
- - **The package says what it is.** The PyPI summary, keywords, README opening, docs index and docs site name both
228
- halves: the framework and the `agentx` terminal assistant, with helpers that run in parallel. New cookbook pattern
229
- 40, "Let helpers work in parallel", for the terminal app and for `AsyncSupervisor` in your own code.
230
-
231
- ### Fixed
232
-
233
- - **The iPad's link keeps working after the computer sleeps.** Tailscale could stop sharing agentx's port (after a
234
- sleep or a Tailscale restart) while agentx still ran, so the link was dead. agentx now checks every 30 seconds
235
- and shares it again (the same link), saying so in the terminal, and at start clears entries earlier runs left
236
- shared with nothing behind them. The tests no longer reach the Tailscale of the machine they run on.
237
- - **The ssh command for another computer uses the Wi-Fi address again.** With Tailscale on, it used this computer's
238
- Tailscale address (100.x), which times out from a laptop without Tailscale; the Tailscale address is now offered
239
- as the one to use from a computer with Tailscale on.
240
- - **The app window shows agentx at work, as the terminal does.** In `/remote-control` from the terminal it said
241
- "Waiting for agentx…" with nothing moving: now the spinner line (what it does, the time and the tokens this
242
- message has used) shows there too, starts the moment a message is sent, and a soft light runs along the message
243
- box while it works. A conversation starts with the agentx header (version, model, folder), like the terminal's
244
- box, and the link and ssh steps of `/remote-control` stay in the terminal instead of filling the window.
245
- - **"Open in Safari" opens the app window, not a box saying to start agentx.** The page took its key out of
246
- the address, so opening it in another browser, a new tab or from a bookmark had none, and the box could not be
247
- closed. The key now stays in the address after a `#` (never sent to the server). Without a key, or with one from
248
- an earlier start, the box says which, and takes the link agentx printed pasted in.
249
- - **`agentx --remote` opens the terminal with remote control on.** Before, `--remote` needed `--ui` and gave the app
250
- window only; now `agentx --remote` is `agentx` followed by `/remote-control` (`--ui --remote` still serves the
251
- window only).
252
- - **When Tailscale gives no link for the iPad, agentx says so first.** HTTPS or Serve turned off in the Tailscale
253
- account (also after it worked) left only the 127.0.0.1 address, with the reason under the SSH steps; now the reason
254
- and where to turn it on come first, Tailscale's own link to allow Serve is passed on, and agentx no longer waits
255
- 20 seconds for Tailscale there.
256
- - **The app window's Details panel fits the screen.** A long MCP server name or address stretched it, so on an iPad
257
- it scrolled sideways; long names and addresses now wrap inside it. Below a wide desktop window (an iPad, a
258
- half-screen window) it slides over the chat instead of squeezing it, and tapping beside it or Escape closes it.
259
- - **`agentx`: a turn that stops before it finishes is kept.** Out of credit, any other error, Ctrl+C or the token
260
- limit used to drop the whole turn, so after switching model (say Claude ran out of credit) the new model did not
261
- know what the stopped turn had changed. Now your message and a short record (files changed, commands run, the last
262
- thing it said, why it stopped) go into the conversation and the work log, and `continue` picks up from there, on
263
- the same model or after `/model <name>`. An out-of-credit error says so plainly and what to do instead of
264
- printing the raw `BadRequestError`. Leaving prints how to come back: `agentx --continue` (with `--model <name>`).
265
- - **`run_shell` and `run_python` stop at their time limit.** On Windows the limit killed only the shell and then
266
- waited, with no limit, for programs it had started (`ssh`, `sleep`, a dev server) to close the output, so a 5-minute
267
- limit could run for as long as such a program did (`Running run_shell... 7m 28s`). The whole process tree is now
268
- stopped at the limit, and the timeout message keeps what the command printed before it. A command that ends but
269
- leaves a program running in the background without redirecting its output (`cmd &`) returns at once with a note
270
- on how to start it (`nohup cmd > log.txt 2>&1 &`) instead of holding the tool until the limit. Commands get an
271
- empty stdin, so none can read the terminal. Ctrl+C while a command runs now stops it and everything it started
272
- (a hung `ssh` used to keep the turn waiting after "Turn interrupted").
273
- - **A helper that calls a tool it does not have is told so and carries on.** A "final checks" step that also had to
274
- fix what failed went to the runner (it runs commands but cannot edit); its call to `edit_file` ended the step with
275
- "(agent emitted an unrecognized action and no answer text)", shown as Done. agentx's agent and helpers now get the
276
- framework's `strict_tool_dispatch` reply (the tool is not theirs, here are the ones they have), a step that still
277
- ends with no report is marked failed, and the planner is told to give a step only to a helper with every tool it
278
- needs.
279
- - **A team job uses the GPT models in `teamModels` too.** With a Claude chat model and `gpt-6-luna` in the list
280
- (its key found), every step of every job ran on a Claude model: the planner was told "no model is preferred" and
281
- picked its own provider. It is now told the user listed these models so the work is shared among them, and, when
282
- the list has both Claude and GPT models, to give at least one step to each provider.
283
- - **Team steps start in plan order.** When a step finished and freed two steps at once, the one that had been waiting
284
- longer went first: step 3 ran before step 2. A step now gives way to an earlier step that is ready at the same
285
- time (for at most 3 seconds, so a step that never starts cannot hold up the rest).
286
- - **The spinner shows minutes**: `Team is working... 11m 23s`, not `683s` (and `1h 02m` past an hour).
287
- - **`agentx --model claude-opus-5.5` works.** A Claude name written with a dot got a 404 ("model: claude-opus-5.5
288
- was not found") on the first message; it is now read as the dashed id (`claude-opus-5-5`). GPT names keep their dot.
289
- - **A `teamModels` note may be 200 characters** (was 80, and a longer one was dropped at every start). A note past
290
- 200 is now shortened, with a warning, instead of dropped.
291
- - **A step with no action and no answer no longer ends the run.** A reply cut off by the output limit (seen with a
292
- Claude Sonnet 5.5 helper after 20 tool calls) came back empty and the run ended with "(agent emitted an
293
- unrecognized action and no answer text)". The model is now asked again, up to twice per run.
294
- - **`agentx` finds an API key saved in Windows after the terminal was opened.** A team model on the other provider
295
- showed `Not used: gpt-... (no OPENAI_API_KEY)` when the key was set with `setx` or the Environment Variables dialog
296
- after the terminal started. agentx now reads a missing `ANTHROPIC_API_KEY` or `OPENAI_API_KEY` from the saved user
297
- (then system) variables at start, before each team job and on `/model`, and says which it used (never the value).
298
- - **A team job's task may be 12,000 characters** (was 4,000): the main agent's detailed tasks were refused twice in
299
- one job.
300
- - **Claude: every agent request was declined on claude-opus-5 and claude-opus-5-5.** The agent's step tool asked
301
- for a `Thought` (the model's reasoning, written out), and these models decline a request that asks for their
302
- reasoning (`stop_reason: "refusal"`, category `reasoning_extraction`) before writing anything: `agentx` showed
303
- nothing at all, or "unrecognized action". The step tool is now sent to Claude without its `Thought` field
304
- (GPT keeps it). And a decline, or `max_tokens` used up with nothing written, now raises `ModelDeclined` with the
305
- provider's reason (also in `agentx.log`) instead of returning an empty answer.
306
- - **Evals: failed tool calls were never counted.** The count looked for results starting with "ToolError" in
307
- `completion.tool_calls`, which lists only the calls that worked, so it was always 0. It now counts them from the
308
- run log, recovered ones included.
309
- - **`agentx`: an installed skill is ready at once.** `/skills install` and `/skills remove` used to wait for a new
310
- conversation (`/clear`, or a restart); now the conversation you are in gets the change, with its history kept.
311
- `/skills reload` does the same for a skill folder copied in by hand.
312
- - **`agentx`: Claude models use prompt caching.** `agentx` built Claude models without it, so every step of a long
313
- run sent the whole conversation again at full price and counted it in full against the token limit (one helper
314
- used 229k tokens on 8 tool calls and stopped part-way). The system prompt, the tools and the conversation so far
315
- are now read from Anthropic's cache on the next step, billed and counted at about a tenth.
316
- - **`agentx`: a run that hits the step limit shows what it did.** It ended with nothing on the screen; it now shows
317
- the summary and says to type `continue`. The limit is 300 steps a message (was 50): `"maxSteps"` in your settings
318
- or `--max-steps` changes it. A short "continue" (or "go on", "carry on", "keep going") right after that stop
319
- tells the agent to pick up from its last step instead of re-running the checks already in the conversation.
320
- - **`agentx`: a team job saves every helper's work as it goes**, in `.agentx/team/<date>-<task>/` (`job.md` and one
321
- file per step with the helper's whole report), and the finished reports join the project's `recall` index: a
322
- closed terminal no longer loses the research.
323
- - **`agentx`: team steps are shown by role.** The planner gives every step a name for what its helper does
324
- (`git-checker`, `payments-fixer`, `migration-verifier`), shown in the plan, the live block, the done lines and
325
- `/team log` in place of `runner` / `coder` (`git-checker@claude-sonnet-5-5`). The step still runs on the
326
- built-in helper; a step without a name shows the helper's as before.
327
- - **`agentx`: `/skills install` fetches only the skill files.** It asks GitHub for the repository's file list and
328
- downloads just the skill folders' files, so a big repository costs what its skills weigh (`morluto/rea`, 6,677
329
- files and 130 MB, was refused as "too many files"; its skill is 8 files). Skills in hidden folders such as
330
- `.agents/skills` are found (they were skipped), a `/blob/.../SKILL.md` link installs that skill, and the archive
331
- fallback counts only the files it unpacks.
332
- - **`agentx`: `/skills install` handles repositories with big demo files.** Only the folders holding a `SKILL.md`
333
- (or the folder the link names) are unpacked, so a repository's videos and docs no longer count: the download may
334
- be up to 100 MB, and a skill's own files up to 10 MB each (music, fonts), 50 MB in all.
335
- `latent-spaces/brag` (65 MB, mostly demo videos) was refused as "bigger than the limit". Names before the link
336
- install only those skills (`/skills install brag <link>`), a misspelt subcommand gets "Did you mean /skills
337
- install?", and an over-limit download says what the limit is.
338
- - **Structured output on Opus 5.5, Sonnet 5.5 and Fable 5.1.** These models answer a forced tool choice with a
339
- 400, which `output_schema` and the answer parser used. The call now goes with `tool_choice: auto` and a line
340
- asking for the tool; another model that refuses it is found from the error and remembered.
341
- - **`agentx`: a saved model whose key is gone no longer stops the start.** When the other provider's key is set
342
- (you moved from GPT to Claude, say), `agentx` lists that provider's models (Claude: `claude-opus-5-5`,
343
- `claude-sonnet-5-5`, `claude-haiku-5-5`, `claude-fable-5-1`) or asks for a name, uses the one picked, and offers
344
- to save it in the settings file the old name came from.
345
- - **An OpenAI model that needs the Responses API for tool calls is found out once per program, not once per model
346
- object.** Each new `agentx` session, team helper and benchmark task used to send one chat-completions request that
347
- the provider rejected before switching. Now the switch is remembered for that model at that address until the
348
- program exits.
349
- - **Benchmark:** a result file keeps the whole model name (`gpt-6.1-sol` was saved as `gpt-6.json`), and an answer
350
- check says which words it found instead of "the answer covers it". The first baseline, 10/10 on `gpt-6.1-sol`,
351
- is in `bench/results/`.
352
- - **`agentx`: cached input counts as a tenth toward the token limit and each team step's share.** A helper's
353
- requests are mostly input the provider serves from its cache, billed at about a tenth, but they were counted in
354
- full: in one audit each explorer was cut off after about 15 calls at "220k tokens", reported partial, and the agent
355
- started two more team jobs. The limit question also says how many tokens were sent in full, and the team block and
356
- done lines show the cached share (`230k tokens, 80% cached`).
357
- - **`agentx`: helpers can open `auditing-a-project`** (version 2; it was listed only for the main agent, so helpers
358
- told to follow it searched the disk for it). A step's report line drops markdown marks (`##`, `**`).
359
-
360
- - **`agentx`: a no at the token-limit question now ends a team job cleanly.** New steps still started after the no
361
- (three explorers at once, in one audit), and skill reads were not refused, so wrapping up ran past its allowance and
362
- the whole turn was thrown away. Now no step starts after a no (it is listed as `not started`), `use_skill` is refused
363
- like every other tool, and the team reports with what it has.
364
- - **`agentx`: files are read with the file tools.** The base prompt and the runner helper say to read files with
365
- `read_path` and search with `grep`/`find_files`, not print them with `run_python` or `run_shell` (one audit's runner
366
- spent its whole token share printing files with Python). Helpers open a skill only when their step names it or it
367
- covers exactly that step.
368
-
369
- - **`agentx` team helpers no longer read the same files over and over.** Helpers kept 12,000 to 24,000 characters of
370
- tool results whole, lost the files they had read and read them again (eight to ten times each on one audit, about
371
- 2.5 million tokens and twelve limit questions). They now keep 20,000 to 40,000 like the chat, and a third whole read
372
- of a file that has not changed in the step gets a note instead (an edit or any command resets it; a read with
373
- `offset`/`limit` always works).
374
- - **A team's report reaches the chat whole.** The result text is cut at 20,000 characters (was 6,000, which cut an
375
- audit's findings and made the agent start a second job).
376
-
377
- - **The wheel installs only `agentx_dev`.** `examples` and `host` (the docs site) were installed as top-level
378
- packages too; they stay in the source download. The license is now an SPDX expression (`MIT`, with
379
- `license-files`), which needs setuptools 77 or later to build.
380
- - **An MCP sign-in survives a restart.** The SDK loaded a saved token as never expiring, sent it after it had run
381
- out, and asked for a new sign-in instead of renewing it; after a restart it also guessed the renewal address
382
- (`<server>/token`, a 404 for Supabase). agentx now keeps when the token runs out and the server's OAuth details from
383
- the sign-in, and hands both back, so the token is renewed at the right address.
384
- - **MCP sign-in to servers that issue a client secret (Supabase).** A secret given without a method is now sent
385
- in the token request; the sign-in failed with "Required parameter: client_secret".
386
- - **One stuck request no longer waits about 12 minutes.** A timed-out request is retried once at most (the client
387
- has usually retried it already; a timed-out request may still be billed), and a 429 waits for its `Retry-After`.
388
- - **A spent budget is not retried.** `CostBudgetExceeded` (and anything `model.on_usage` raises) is raised once; on
389
- the plain chat path the call used to be retried up to three times after the budget was spent, paying each time.
390
-
391
- ### Added
392
-
393
- - **A benchmark for `agentx`** (`python -m bench`): ten fixed tasks on two sample repos (find, explain, fix, fix and
394
- test, validate, add a feature, rename, audit, a team job, run and report), each checked automatically (the tests,
395
- hidden tests, the files), with pass/fail, time, model requests, tokens, the cached share and tool calls recorded;
396
- `compare` sets two runs side by side. It asks before it uses your API key. See `bench/README.md`.
397
- - **`agentx`: `/mcp reload [name]`** (also `/mcp refresh`): reads `~/.agentx/mcp.json` again and reconnects every
398
- server (or one) with the saved sign-ins, never opening the browser; servers taken out of the file are dropped and
399
- the conversation gets the new tools. On Windows it also reads the user's saved environment variables, so a key set
400
- with `setx` after the start is found. `MCPManager.reload(name=None, env=None)`.
401
- - **`agentx`: full-screen mode** (`agentx --fullscreen`, `/fullscreen on|off`, `"fullscreen": true` in
402
- `~/.agentx/settings.json`; off by default). The welcome box, the input and the status line stay put while only the
403
- conversation scrolls (mouse wheel, PgUp / PgDn, Ctrl+End). Questions are asked above the input; a message typed
404
- while the agent works is kept for later; Ctrl+C and Ctrl+D work as before; on exit the conversation is written to
405
- the terminal. The app runs unchanged on a worker thread: its console writes into the screen, and the spinner is
406
- drawn by the screen (`Progress.drawn_by`).
407
- - **`agentx`: the agent looking around is one tree.** Skill reads, `recall`, reads, searches, listings and web calls
408
- in a row are drawn as one flow (`● Skills using-superpowers` / `├─ recall ...` / `│ ⎿ Found 2 notes` /
409
- `└─ read_path ...`), redrawn in place above the spinner while it runs (a blinking yellow dot, the running step
410
- blinking white) and printed when the agent moves on, with a green dot (red when the last step failed). The agent's narration leading into those steps or into its answer is no longer printed; a note before
411
- an edit or a command still is.
412
-
413
- - **`agentx`: the supervisor can make helpers.** A plan step may define a helper (`new_agent`: a name, instructions,
414
- tools). agentx builds it the way it builds explorer, coder and runner (gated tools, step
415
- wrapping, redaction, 100 steps, trimming, skills); its tools come only from the gated set, never `delete_path`,
416
- `move_file`, `start_team_job` or `delegate`, and it gets only the MCP tools it names. A helper with only reading
417
- tools runs beside other reading steps. At most 6 per job; the plan shows each one and its tools. With helper
418
- models set (`/team-models`), it may run on one of them (`"model"` in `new_agent`, read before the plan checker drops
419
- it): the planner is told the list, a model not on it is not used, and the name shows it (`reviewer@gpt-6-luna`).
420
- - **`Skills(guard=fn)`**: `fn()` is asked before each `use_skill` read; a text it returns is the answer instead.
421
- - **`agentx`: reading steps of a team job run side by side.** Explorer steps that do not depend on each other run
422
- up to 3 at once (`AsyncSupervisor` with `max_parallel=3` and a lock: a coder or runner step runs alone). A plan
423
- without `depends_on` keeps its order, with neighbouring explorer steps grouped. Helpers run in worker threads; every
424
- approval, team question, limit question and screen line is handed to the main thread, so prompts never overlap,
425
- and Ctrl+C stops the job at once (a helper stops at its next tool call or model reply).
426
- - **`agentx`: each team step has a token share,** one token limit's worth (at least 100,000); past it the step's
427
- tools tell the helper to report what it has.
428
- - **`agentx`: `a` at the token-limit question** goes on and does not ask again in this message.
429
- - **`agentx`: team helpers work in the background.** Their tool calls are no longer printed. A block above the
430
- spinner, redrawn in place, shows one line per running step (helper · step name, what it has done, time, tokens);
431
- a finished step leaves one line (`✓ explorer · security audit Done (20 tool uses · 41k tokens · 1m 30s)`) and the
432
- start of its report. `/team log` lists every call of the last team job. Steps are named by their plan id.
433
- - **The `auditing-a-project` skill** (bundled): map, run the project's own checks, read by area with explorers side
434
- by side, verify, and report Fix first / Medium / Low / Done well / Checks / Test gaps. `delegating-work` (version
435
- 2) says which steps run side by side.
436
-
437
- - **Smaller requests.** `AgentRunner(..., trim_results=True)` (and `AsyncAgentRunner`, or a `TrimPolicy` from
438
- `agentx_dev.Runner.Trim`) sends the model a one-line stub in place of each big tool result outside a window of the newest
439
- ones (20,000 to 40,000 characters, moved in steps, at least the newest one), stubs an older word-for-word copy of a later result, and shortens long
440
- arguments of old calls; the saved history is unchanged and `use_skill` results are never
441
- trimmed. `Permissions.read_max_chars` makes `read_path` return a long file in numbered parts with a note on how
442
- to continue. `Skills(remember_reads=True)` answers a second read of a skill with a pointer back.
443
- - **`agentx`:** all of the above are on (reads in parts of 30,000 characters); summarising starts at 60,000
444
- characters (was 150,000) and is measured on what the model is sent. On a measured 15-file turn the input sent
445
- fell from about 231,000 tokens to about 136,000. `/usage` shows the tokens used this session, per model, and by
446
- the last turn.
447
- - **Fewer whole-file re-reads.** A trimmed `read_path` result now names the file and its line count (or the line
448
- range of a slice) and says to grep it or read only the lines needed; `agentx`'s base prompt and the
449
- `exploring-a-project` skill (version 3) tell agents to write down the facts they will need as they read.
450
- - **Cache-friendly trimming.** `TrimPolicy(step_chars=)`: once the whole results pass `keep_chars`, the oldest are
451
- stubbed in one go down to `keep_chars - step_chars` (default half), so the start of the request stays the same,
452
- and cacheable, until the next step; `keep_last` is now 1. Team helpers keep 12,000-24,000 characters. On a replayed
453
- 40-step team brainstorm the input cost fell by about 28-41%, depending on the cached price.
454
- - **A short `AGENTX.md`.** This repo's `AGENTX.md` is now about 1,800 characters (was 13,300), since `agentx` sends
455
- it with every request; the full guide moved to `docs/reference/agent-guide.md`.
456
- - **Older skill texts are stubbed in a long conversation.** `TrimPolicy(shrink_exempt_at=60_000)`: past that many
457
- characters of conversation, every `use_skill` result but the newest is sent as a note that the skill still applies
458
- and how to reopen it. In `agentx`, `run_python` and `run_shell` output is cut at 30,000 characters (was 100,000 and
459
- 40,000), with a note to print less. Replaying a 21-step message that read five skills, the input sent fell by
460
- about 15%.
461
- - **OpenAI cached tokens are counted** (`TokenUsage.total_cache_read_tokens`, from either API), and `/usage` shows how
462
- much of the input came from the provider's cache.
463
- - **A token limit per message in `agentx`.** Past 200,000 tokens (`/limit`, `"tokenLimit"` in settings; a project
464
- may only lower it) agentx asks before it goes on; a no wraps up (tool calls are refused, the agent answers with
465
- what it has, the turn is kept), and only a wrap-up that runs long too ends the turn like Ctrl+C.
466
- `BaseChatModel.on_usage`, a hook called after every recorded reply, is what it uses.
467
- - **Web tools in `agentx`.** `web_search` and `web_fetch` (readable text, at most 30,000 characters, marked as data
468
- from the internet); the gate asks before each in `default` and `plan` mode (`a`: the rest of the session). The
469
- `web-research` skill is listed, and the team's explorer gets them.
470
- - **MCP servers in `agentx`.** `/mcp add <name> <url>` (`--sse`), `/mcp add <name> -- <command> [args]`, `/mcp remove`,
471
- `/mcp login`, `/mcp logout`; kept in `~/.agentx/mcp.json`, `${VAR}` for keys. A browser sign-in (OAuth) runs only on
472
- `/mcp login`; tokens go to the system's credential store (`keyring`, split across entries when long) and renew
473
- by themselves. Tools appear as `<server>__<tool>` for the chat and every team helper, ask before running even in
474
- auto mode, and their results are marked as outside data and cut at 30,000 characters. The `mcp` extra now needs
475
- `mcp>=1.10,<2` (2.x changed the client API and is not supported yet) and `keyring>=24`.
476
- - **MCP tools sorted by what they do.** The first time agentx sees a server's tools, the ones the server marks
477
- read-only run without asking (saved per server in `mcp.json` as `allow`/`seen`); the rest ask. `/mcp tools <name>`
478
- lists them, `/mcp allow|ask <name> <tool...|read-only|all>` changes them; allowing a destructive tool asks first.
479
- - **Model requests in `agentx` wait up to 5 minutes and are retried visibly.** `model.on_retry(attempt, error,
480
- delay)` is called before each retry; `agentx` prints a line.
481
- - **Tool results are one line in `agentx`.** Under each call: `⎿ Read 51 lines`, `⎿ Found 2 files`, `⎿ 3 matches in
482
- 12 files searched`, `⎿ Found 1 note`, a command's first line of output and how many more, or its exit code and
483
- last line in red when it failed. Refusals and errors are still shown in full.
484
- - **Skill reads are one line in `agentx`.** Their text is never printed; a run of them shows on the spinner as it
485
- grows and then stays as `● Skills a → b → c (+ file)`, with the notes written meanwhile after it. A failed read
486
- is still shown.
487
- - **A new `agentx` start screen.** A box with the agentx mark, the model and folder, tips for this folder and
488
- what's new; MCP sign-in problems as one warning line; notes with a bar down the left; a rule above the input
489
- and the mode under it (`⏵⏵ auto mode on (shift+tab to cycle) · model · folder`).
490
- - **`agentx` input colours:** the `/name` at the start of the input line is coloured as you type (command cyan, skill
491
- magenta, unknown red) and the selected row of the `/` pop-up is highlighted.
492
- - **Skills first.** The skill list tells the model to check it before choosing tools and to prefer a skill the user
493
- installed when it fits; the user's own skills are listed ahead of the built-in ones, and the terminal app's base
494
- prompt says the same.
495
- - **`agentx` project notes and recall:** a readable note per worthwhile turn in `.agentx/notes/` (asked, result,
496
- files changed, commands), indexed in `.agentx/memory/` with OpenAI embeddings when `OPENAI_API_KEY` is set
497
- (local similarity search otherwise, keywords if both fail). The agent gets a `recall` tool, a fresh
498
- conversation's first message gets up to 3 close notes, and `/memory [words]` shows or searches them.
499
-
500
- - **Skills.** `AgentRunner(..., skills=True)` (and `AsyncAgentRunner`) gives an agent a `use_skill` tool and a short
501
- list of skills at the end of its system prompt; the model reads a skill's full text only when it needs it. The
502
- list is built the same way every time, so the prompt stays identical for the provider's prompt cache. Five
503
- skills ship with agentx (`exploring-a-project`, `changing-files`, `running-code`, `web-research`,
504
- `delegating-work`) and are created in `~/.agentx/skills/` on first use; edits and deletions are respected. The
505
- agent's own tools are described by a generated `custom-tools` skill. `SKILL.md` folders written for Claude work
506
- as they are. See the new [guide](docs/guides/skills.md).
507
- - **`agentx` terminal app:** skills are on by default; `/skills` lists them, `/skills install <github link or
508
- folder>` installs after showing what it found (the exact commit is downloaded and recorded; archives are
509
- unpacked with path, link and size limits), `/skills remove <name>` deletes one. Every skill the agent has is also a slash command: typing `/` lists the commands and then the skills, and `/<skill> [what you want]` (or `/skills use <name> ...` for a skill named like a command) makes the agent read that skill and do the task. Team helpers get `use_skill` and the skills that fit their role's tools, so a team step can use a skill; a helper's skill reads show on screen like its other tool calls (`● [explorer] use_skill brainstorming`); `/skill` is a short form of `/skills`. Only the user can install: the
510
- agent has no tool for it, and `.agentx/*` and `~/.agentx` stay protected from its file tools.
511
-
512
- ## [3.7.0] - 2026-10-15
513
-
514
- ### Added
515
-
516
- - **The `agentx` command**: a terminal coding assistant (`agentx`, or `python -m agentx_dev`), built on
517
- `AgentRunner`, `DefaultTools` and `Session`. Run it in a project folder; it works with GPT and Claude from
518
- `OPENAI_API_KEY` / `ANTHROPIC_API_KEY`. Flags: `--model`, `--mode`, `--add-dir`, `--continue`,
519
- `--resume [ID]`, `--version`. See the new [guide](docs/guides/cli.md).
520
- - **Approvals and modes.** Reads run; edits, commands and delete / move ask first, with a diff or the full
521
- command shown. Modes `default`, `accept-edits`, `plan` and `auto` (edits, shell and Python run without asking; delete, move and unknown tools still ask; entered only on purpose, never from Shift+Tab, an `a` answer or a project settings file). Answering `a` ("don't ask again") remembers
522
- all edits or a plain command prefix for the conversation, never for interpreters, shells, compound
523
- commands, `run_python`, delete or move. A preview that cannot be shown, or a command over 20,000
524
- characters, is declined with the reason.
525
- - **Default protections.** Writes, edits, deletes and moves of the whole `.git`, of `.agentx/*` in the
526
- project, and (when the home folder is reachable) of `~/.agentx`, git config files and common shell
527
- profiles are always refused, in every mode. Deny and allow rules are a convenience layer, not a secrets
528
- vault: `grep`, `find_files` and `list_directory` can still read a file a read rule denies, and
529
- `run_shell` / `run_python` are not covered by path rules.
530
- - **Settings and rules.** `~/.agentx/settings.json` and `.agentx/settings.json` (`model`, `mode`,
531
- `addDirs`, `permissions.allow` / `deny` as `tool:glob`). Project settings are untrusted: an
532
- `accept-edits` mode and `addDirs` outside the project are ignored with a warning, and the project's
533
- allow rules are listed at startup and honoured only if you answer yes to "Honour these project rules?"
534
- (deny rules from the project are always kept).
535
- - **`AGENTX.md` context.** `~/.agentx/AGENTX.md` and the files from the working folder up through its
536
- parents are passed to the model as instructions (nearest last, 20,000 characters); `/init` drafts one.
537
- - **Sessions.** Conversations autosave to `~/.agentx/sessions/` and resume with `--continue`,
538
- `--resume` and `/resume`. The files hold tool results (file contents) and are not encrypted.
539
- - **Team jobs.** For a big job the chat agent can call `start_team_job` (the user approves each hand-off,
540
- unless you run in auto mode or have allowed it with your own rule; `/team <task>` does it by hand): a
541
- `Supervisor` plans up to six steps and three helpers (explorer reads,
542
- coder edits, runner runs commands) carry them out one at a time. Every helper call goes through the same
543
- gate, modes, deny rules and prompts as the chat; the result joins the conversation. A deny rule
544
- `start_team_job:*` turns it off.
545
- - **Helper models for team jobs.** Allow extra models with `teamModels` (in either settings file; a folder's
546
- list replaces yours) or `/team-models`, and the supervisor picks per step which model a helper runs on
547
- (Claude and GPT can be mixed when both keys are set). Every helper then names its model, the chat's own
548
- included (`coder@claude-opus-5-5`, `runner@claude-sonnet-5-5`), with the same wording for every model so
549
- none is favoured, and each model can carry a note on what it is for (`gpt-6.1-sol="hard coding"`), which
550
- the supervisor reads; without one, the chat model is asked once what each model is good for and its
551
- answer is kept as an `auto:` note (`/team-models describe` asks again). The approval box lists the models. A list that comes from a project's settings file
552
- is announced at startup. With no list nothing changes. Team helpers now get 100 steps (was 25); a helper
553
- that runs out of steps hands on its partial work instead of failing the step, and one message may run up to
554
- 5 team jobs, so a big task continues batch after batch without you typing "continue". See the guide.
555
- - **Project memory.** Each folder can have its own model: the first time you trust a folder, `agentx`
556
- writes `.agentx/settings.json` with the model in use, and `/model <name> --folder` changes it (plain
557
- `/model <name>` stays for the session). The app keeps a work log in `.agentx/log.md`, written by the app
558
- (not the model) after each finished turn with the request, the files changed, the commands run and the
559
- start of the answer; keys are hidden and the file is readable by its owner only where the platform
560
- allows. A fresh conversation (a start without `--continue` / `--resume`, and `/clear`) starts from the
561
- newest entries of that log, and a very long conversation is summarised before it overflows (the older
562
- messages become one summary; the last six of your messages stay as they were). Not kept for the home
563
- folder or a drive root. See the guide.
564
- - **Slash commands.** `/help`, `/clear`, `/model`, `/mode`, `/settings`, `/resume`, `/sessions`, `/init`,
565
- `/team`, `/team-models`, `/exit`. Typing `/` pops up the list with a one-line description of each. The
566
- first run writes `~/.agentx/settings.json` with the model in use, once it is built, so there is a file to
567
- edit; `/settings` shows what is in force and where the files are. A `"model": "(no model)"` line that an
568
- earlier build of this release could write there is ignored with a warning to delete it.
569
- - **Trust and menus.** The first start in a folder asks whether you trust it ("Accessing workspace", Yes /
570
- No); nothing from the folder (`AGENTX.md`, project settings) is read before you answer, and the answer is
571
- kept in `~/.agentx/trusted.json`. Choices are numbered menus you move through with the arrow keys and
572
- confirm with Enter (or a number, or `y` / `a` / `n`): the approval prompt, the folder question and the
573
- `/resume` list. Without a terminal they fall back to typed answers.
574
- - **A prompt that looks alive.** The input prompt is coloured and its cursor blinks while it waits for you.
575
- - **Progress.** While the agent works, a spinner with the seconds elapsed shows what it is doing
576
- ("Thinking...", "Running run_python... 12s"). It is paused while a prompt waits and drawn only on a
577
- terminal. Python code may run for 2 minutes and shell commands for 5 (the framework's defaults, 10 s and
578
- 30 s, stopped web fetches and test runs); time spent waiting for approval does not count.
579
- - **`Session.stream(user_input, **kw)`**: like `Session.invoke`, but yields the runner's events and absorbs the
580
- result on the final `completion` event. A turn abandoned before then is not recorded.
581
- - **New base dependency: `prompt_toolkit>=3.0`** (the input line: history, multi-line, completion, status
582
- bar). `rich` was already a dependency.
583
-
584
- ### Fixed
585
-
586
- - **A conversation can continue after a run that ended on a final answer given as a function call.** With
587
- function calling the model delivers its answer as a call (`React_` or `respond`) and the run ended
588
- without a result for it, so the next turn was rejected by OpenAI ("An assistant message with
589
- 'tool_calls' must be followed by tool messages" / "No tool output found for function call"). The history
590
- a run returns now closes that call, and a history saved by an older version is repaired when resumed.
591
- This affects `Session` and `chat_history` users as well as the CLI.
592
- - **`edit_file` no longer rewrites a file's line endings.** It read and wrote through the platform's newline
593
- translation, so on Windows an LF file came back CRLF and on Linux and macOS a CRLF file came back LF, with
594
- every line changed. It now keeps every byte outside the edit. A model's bare newlines in `find` and
595
- `replace` are put in the file's own ending (CRLF if the file mostly uses it), so CRLF files can be edited
596
- across lines.
597
-
598
- ## [3.6.2] - 2026-10-09
599
-
600
- ### Added
601
-
602
- - **`Supervisor(ask_when_done=True)` / `follow_up=True`** (and the same on `AsyncSupervisor`): when a
603
- round's answer is ready the framework itself asks the operator "What should I do next?" through the
604
- `ask_user` asker (the answer, the outcome and the question in one prompt) and returns the reply in
605
- `SupervisorResult.next_step`. `follow_up=True` runs another round on each reply, with the earlier
606
- results as context, until the operator replies blank or with a closing word (any of `done`, `stop`,
607
- `quit`, `exit`, `no`, `nothing`, `that's all`, `that's it`, `all done`, `nope`, `bye`, `goodbye`,
608
- `thanks`, `thank you`, `no thanks`, `no thank you`, `done thanks`, `done thank you`, `nothing thanks`,
609
- `stop thanks`; case-insensitive; apostrophes (`thats all` works), commas, extra spaces and trailing `.`, `!`, `?` ignored); `max_follow_ups` (default
610
- 5) bounds it and `SupervisorResult.rounds` lists the rounds. Asked whatever the outcome. The
611
- checkpoint uses no `max_questions` slot and is never saved to memory; only round 1's result is.
612
- New `checkpoint` and `round` stream events. Either setting needs `ask_user`. With `ask_when_done`
613
- on, the Supervisor asks itself, so the planner and the helpers are told not to ask "what next?"
614
- (no double question); the built-in terminal prompt puts the question first.
615
-
616
- ### Fixed
617
-
618
- - **"When done, ask me" now reaches `ask_user`.** With `ask_user=True` and a task that said to ask the
619
- operator what to do when finished, the helper wrote the question into its answer and the run ended
620
- with nobody to answer. A helper's instruction covered only a missing fact; it now also covers a task
621
- that tells it to check with the user, and says to call `ask_user` at that point and act on the reply.
622
- The planner is told to put that instruction in the step's query rather than plan a step that only
623
- asks.
624
-
625
- - A planner-defined helper built with no tools (a research step the planner forgot to give `web`) is
626
- now called out in the verbose `[spawn]` line ("no tools, so it can only reason"). The planner is
627
- reminded, as the last rule of the helper instructions, to give every `new_agent` the tools its job
628
- needs, and `capabilities` is accepted as an alias for `tools` in a `new_agent` (the 3.5 spelling).
629
- - The verbose line "has the same tools as the registered specialist" no longer fires because both
630
- agents were given `ask_user`.
631
-
632
- ### Changed
633
-
634
- - **The vector-store clients are core dependencies.** `chromadb`, `qdrant-client` and `psycopg[binary]`
635
- now install with `pip install agentx-dev`, so `ChromaVectorStore`, `QdrantVectorStore` and
636
- `PgVectorStore` work without an extra. `[chroma]`, `[qdrant]` and `[pgvector]` remain as aliases.
637
- The base install is larger (chromadb brings onnxruntime and others); `anthropic`, `mcp` and
638
- `opentelemetry` are still extras.
639
- - The planner's catalog lists each registered agent's tools under its description (framework tools
640
- `ask_user` and `delegate` left out, long lists cut at 12), so a description no longer has to say
641
- that an agent can write files. Registered agents whose runner has no tool registry are unchanged.
642
- - The verbose `[spawn]` line ends with `+ ask_user` for a helper that can ask. `result.spawned` is
643
- unchanged.
644
-
645
- ### Docs
646
-
647
- - Sub-agents guide: how to let helpers write files (`capabilities={"web", "files"}` and
648
- `allowed_paths`), the capability words, and asking at a checkpoint; FAQ entry.
649
-
650
- ## [3.6.1] - 2026-10-09
651
-
652
- ### Fixed
653
-
654
- - A package that was installed but failed to import was reported as not installed. A user whose project
655
- folder held a `google.py` saw "ChromaVectorStore requires the chromadb package" although chromadb was
656
- installed: the file hid the real `google` package that chromadb's dependencies use, and the catch-all
657
- hid that. The error now says which case it is. Not installed: it names the extra
658
- (`python -m pip install "agentx-dev[chroma]"`) and the Python that is running. Installed but failing:
659
- it shows the real error and common causes (a file named like a library, a version conflict) and no
660
- install command. Applies to `ChromaVectorStore`, `QdrantVectorStore`, `PgVectorStore`, `MCPClient`,
661
- `OTelHook` and `Claude`.
662
-
663
- ### Docs
664
-
665
- - Install pages list the `chroma`, `qdrant` and `pgvector` extras and say why a plain install leaves
666
- them out; the troubleshooting page covers both messages.
667
-
668
- ## [3.6.0] - 2026-10-09
669
-
670
- Sub-agents: the Supervisor can create its own helpers. Opt-in, with the behavior changes listed below.
671
-
672
- ### Added
673
-
674
- - **Inline helpers**: a plan step can carry `new_agent` (name, free-form
675
- instructions, tools). The helper runs the step, is reused by name, and is
676
- discarded when the run ends. Recovery plans can define a replacement for a
677
- stuck step.
678
- - **`delegate` tool**: specialists hand a side job to a fresh sub-agent (clean
679
- context) and get a short summary back; refusals are plain text and a helper
680
- that fails comes back as a tool error the caller's stuck logic sees.
681
- `AgentRunner(..., delegation=SpawnConfig(...))` gives a standalone runner the
682
- same tool; `runner.spawned` lists what it created.
683
- - **One ceiling**: `SpawnConfig(capabilities=..., tools=..., max_spawns=...,
684
- max_depth=...)` bounds every helper; spawns inside it need no approval and
685
- over-asks are clipped, not fatal. New read-only `files_read` preset.
686
- - **`AsyncSupervisor(spawn_config=...)`**: async parity; spawned steps run in
687
- parallel. `AsyncAgentRunner` gained `system_addendum=`.
688
- - `SupervisorResult.spawned`, `spawn` and `delegate_result` stream events,
689
- `AgentSpec`, `ToolRegistry.unregister`, `AgentRunner.add_tool` /
690
- `remove_tool`.
691
- - New guide: Sub-agents.
692
- - **Ask the operator**: `Supervisor(ask_user=True | function)` lets the planner ask for facts the task
693
- leaves out and gives every agent an `ask_user` tool. `True` uses a built-in asker that works in
694
- notebooks (the input box), terminals and IDE consoles and never blocks a headless process; a
695
- function routes questions through your own channel (chatbot, backend). `max_questions`,
696
- `ask_timeout`, `SupervisorResult.asked`, `question`/`answer` events,
697
- `agentx_dev.ask_human_tool()`; waiting on the operator pauses the persistent deadline. The built-in prompt names who is asking (`[planner]` or the agent's name) with a raised-hand marker. Each agent
698
- may ask once per run (the planner may ask several questions in its one round), and after the
699
- operator answers the planner is told to do the work instead of planning another question. The
700
- helper-creation instructions now say a helper can only look things up with the tools it is given
701
- (this applies to every Supervisor that enables spawning).
702
- - **Supervisor long-term memory**: `Supervisor(memory=store)` (any vector store: `VectorStore`, Chroma,
703
- Qdrant, pgvector) gives the planner and every dispatched step the few relevant stored items as a
704
- FROM MEMORY block, saves each operator answer and each completed run's final answer, and answers an
705
- exact repeat of an answered question from memory (a run whose synthesis was cut off by the budget
706
- saves nothing). `memory_top_k`, `memory_min_score`,
707
- `memory_write`, `SupervisorResult.memory`, `memory` stream events.
708
- - `web_fetch_tool(text_only=True)`: return an HTML page as readable text (scripts, styles and tags
709
- removed) instead of the first 50,000 characters of raw markup, which on a modern page can hold no
710
- content at all. Default off (unchanged for existing agents); the helpers a Supervisor builds use it.
711
- Helpers are also told not to answer with a script unless they have a code tool, and to say what
712
- they tried and what was missing.
713
- - `SpawnConfig(max_iterations=15)`: the step limit for the helpers a Supervisor creates (it was fixed at 15).
714
- Registered specialists keep the limit set on their own `AgentRunner`. Helpers are told their step limit
715
- so they can finish with a Final_Answer in time.
716
- - A helper that runs out of steps (`iteration_limit`) is retried with a note that it ran out, a short
717
- recap of what it did, and an instruction to do fewer lookups; other failures keep the generic retry note.
718
- - The unknown-tool error now lists the valid tools and says that a response-format name such as `React_`
719
- is not a tool, so a model that called one can recover.
720
- - `RunBudget` now carries a `PausableClock` (it holds a lock), so a `RunBudget` can no longer be
721
- deep-copied or pickled.
722
-
723
- ### Changed
724
-
725
- - A spawned agent no longer stays on the supervisor after the run.
726
- - A spawn is no longer refused (or rerouted) because an existing specialist
727
- has the same tools. The `spawn` event gained `origin`, `tools`, `dropped`,
728
- `reused` and `refused`; `rerouted_from` is always `None`.
729
- - A `Supervisor` / `AsyncSupervisor` with `persistence=` and no `spawn_config`
730
- now allows helpers with web and read-only file access (`max_spawns=6`) and
731
- gives its specialists the `delegate` tool. Pass
732
- `spawn_config=SpawnConfig(enabled=False)` to opt out.
733
- - A legacy spawn config (`enabled=True` with neither `capabilities` nor
734
- `tools`) keeps the 3.5 approval flow and gives specialists no `delegate`
735
- tool; set a ceiling to turn delegation on.
736
- - The planner prompt teaches `new_agent` instead of the `__spawn__` step; old
737
- `__spawn__` steps still work, but their `name` must now match
738
- `[A-Za-z0-9_-]{1,40}`.
739
- - Agent names starting with `__` and names of the form `delegate_<N>` are
740
- reserved: a `new_agent` that uses one is dropped by plan sanitization.
741
- - `SpawnConfig.max_spawns` is `Optional[int]` (unset: 3, or 6 in ceiling mode).
742
- `SUPERVISOR_SPAWN_INSTRUCTION` was removed.
743
-
744
- ## [3.5.0] - 2026-10-04
745
-
746
- Agents that keep working through errors. Opt-in; one default change (below).
747
-
748
- ### Added
749
-
750
- - **Persistent mode** (`persistence=Persistence(...)`) for `AgentRunner`,
751
- `AsyncAgentRunner`, `Supervisor` and `AsyncSupervisor`. When a run gets
752
- stuck (the same call repeated, or tool errors in a row) it is
753
- asked, in four escalating steps, to find the root cause, try a
754
- different approach, probe its assumptions, and say what blocks it,
755
- before it may stop; real progress resets the ladder. Runs stop on
756
- `max_minutes` or the model's cost cap, not a step count.
757
- - **Context compaction** for long runs: old turns become notes, the task
758
- (with its attachments) and recent turns are untouched, and the failed
759
- attempts are kept word for word.
760
- - **Patient retries**: transient provider errors (429, 5xx, timeouts,
761
- connection errors) are retried with backoff until the deadline; auth
762
- and invalid-request errors still raise at once.
763
- - **Supervisors replan**: a step that does not finish is replanned
764
- around under one shared deadline; finished steps are kept and can be
765
- depended on. A recovery step names the steps it redoes
766
- (`"replaces": [...]`); a failed step counts as resolved only when its
767
- replacement finishes. New `replan`, `reflect`, `compact` and `budget`
768
- stream events.
769
- - **Outcomes**: every completion has `.outcome` and (persistent runs)
770
- `.progress`; `SubtaskResult` and `SupervisorResult` have `.outcome`.
771
- - New guide: Long-running agents.
772
-
773
- ### Changed
774
-
775
- - A `Supervisor`/`AsyncSupervisor` now treats a specialist that finished
776
- with an outcome other than `done` (for example `iteration_limit`) as a
777
- failed attempt: it retries up to `max_subtask_retries` with the reason
778
- fed back, then flags the step. Previously such a result was accepted
779
- as a success. This applies without `persistence`. Consequences: each
780
- give-up costs one extra attempt by default (`max_subtask_retries=1`);
781
- the flagged step's recap is no longer passed to downstream
782
- specialists; steps that `depends_on` it are skipped; and
783
- `SupervisorResult.outcome` is `partial` or `stuck`.
784
- - While `persistence` is set the tool-result cache is off, and the
785
- iteration cap is `persistence.max_turns`.
786
-
787
- ## [3.4.3] - 2026-09-26
788
-
789
- Two path-resolution fixes for Windows sandboxes. Non-breaking.
790
-
791
- ### Fixed
792
-
793
- - **`full_access(["/workspace"])` now means the project's workspace
794
- folder, not the drive root.** On Windows a rooted path without a drive
795
- letter resolves to the current drive, so the sandbox became
796
- `C:\workspace`; `auto_create_paths` then created it, and an agent
797
- asked for `workspace/spam.csv` searched an empty directory outside the
798
- project and reported the file missing. Slash-rooted sandbox roots are
799
- now re-rooted at the running project, matching what a leading slash
800
- already meant for tool arguments. POSIX absolute paths (`/workspace`
801
- as a Docker mount) and drive-qualified paths are untouched.
802
- - **`workspace/report.md` no longer nests into
803
- `<workspace>/workspace/report.md`.** The `workspace` field documented
804
- this pass-through, but only the `./workspace/...` spelling had it.
805
- Models name the workspace folder constantly, so the missing case hit
806
- often; new files still resolve into the workspace as before.
807
-
808
- ## [3.4.2] - 2026-09-19
809
-
810
- `media=` everywhere, CSV / text / Excel attachments, and structured output
811
- on models that need the Responses API. Non-breaking.
812
-
813
- ### Added
814
-
815
- - **`media=` on chat models and structured output.** `llm.invoke`,
816
- `llm.ainvoke`, and `with_structured_output(...).invoke` / `.ainvoke` take
817
- `media=[...]` (paths, URLs, `Media`, part dicts), appended to the last
818
- user turn, matching the agent runner. Media inside `content` lists
819
- already worked; this adds the argument.
820
- - **CSV, text files, and Excel in `media=`.** Text-like files (CSV, TSV,
821
- TXT, Markdown, JSON, XML, YAML, HTML) are read as text -- exactly as
822
- written, UTF-8 or Windows-1252, CRLF normalised -- and spreadsheets
823
- (.xlsx / .xls / .ods) are converted with pandas (`dtype=object`, so
824
- cell values aren't re-inferred) to one CSV block per sheet. Both reach
825
- GPT (chat and Responses) and Claude as a labelled text block, which
826
- every model accepts. New `Media.text()` / `Media.spreadsheet()`; a
827
- 100,000-character cap (`max_chars=`, `truncate=True`). pandas and
828
- openpyxl are now core dependencies, so spreadsheets work after a plain
829
- `pip install agentx-dev` (`[excel]` still works). Date cells without a
830
- time are written as dates, not `... 00:00:00`.
831
- - **Media docs section.** Its own nav group: Overview & flow, With chat
832
- models, With agents, Reference (constructors, per-provider wire
833
- formats, errors). `docs/guides/media.md` is now a pointer to it.
834
-
835
- ### Fixed
836
-
837
- - **`with_structured_output` on models that need the Responses API.**
838
- Structured output forces a single tool; if the Responses API rejects a
839
- forced tool choice for the model, `GPT` retries with
840
- `tool_choice="required"` (the same tool when there is only one), then
841
- `"auto"`, remembering it per model. `StructuredOutputRunnable` also
842
- accepts a JSON text answer that validates against the schema.
843
- - **`.txt` media failed on Claude.** 3.4.0 stored text files as base64
844
- documents, which Anthropic only accepts for PDFs. Text files now go
845
- out as text; older base64 text parts in saved histories are decoded
846
- on the way out.
847
- - **Unsupported files reached the provider.** `Media.document()`
848
- accepted any file type -- including CSV, which Windows' own type table
849
- labels `application/vnd.ms-excel` -- and sent it as an attachment
850
- neither provider accepts. Word, PowerPoint and archives now raise
851
- `ValueError` with the fix before any request; a text file or
852
- spreadsheet by URL raises too, since only PDFs can be fetched by URL.
853
- - **Misleading WARNING on recovered calls.** The retry wrapper logged
854
- every non-retryable 400 at WARNING before the caller could recover, so a
855
- call that switched to the Responses API and succeeded still printed the
856
- original "Function tools with reasoning_effort are not supported" text.
857
- Now DEBUG; recoveries log their own WARNING and real failures log ERROR.
858
-
859
- ## [3.4.1] - 2026-09-18
860
-
861
- Tool calls on OpenAI models that require the Responses API.
862
-
863
- ### Fixed
864
-
865
- - **Tool calls failed on models that need the Responses API.** Some
866
- OpenAI models (e.g. `gpt-6-astra`) reject function tools combined with
867
- reasoning on `/v1/chat/completions`, and the error's suggested fix --
868
- `reasoning_effort='none'` -- is itself rejected by those models, so
869
- 3.4.0's parameter adaptation had nowhere to go. `GPT` now switches a
870
- model's tool calls to `/v1/responses` when the provider says to,
871
- retries, and remembers it (WARNING-logged). History is translated only
872
- at the wire (`function_call` / `function_call_output` items paired by
873
- `call_id`), so agents, `tool_calls`, and completions are unchanged.
874
- Learned parameter fixes carry across endpoints (`reasoning.effort` maps
875
- to `reasoning_effort`). Requests are sent with `store=False`, matching
876
- chat completions. Plain text calls and streaming stay on chat
877
- completions.
878
- - Requests chat completions can't express (a document URL) go to the
879
- Responses API, which accepts `file_url`, instead of raising.
880
-
881
- ### Added
882
-
883
- - `GPT(use_responses_api=None | True | False)`: automatic (default),
884
- always, or never.
885
-
886
- ## [3.4.0] - 2026-09-18
887
-
888
- Media input for GPT and Claude, models that adapt to each generation's
889
- parameter support, and workspace-rooted paths. Non-breaking; two
890
- defaults changed -- see docs/guides/upgrading.md.
891
-
892
- ### Added
893
-
894
- - **Media input for GPT and Claude.** New `Media` type
895
- (`Media.image()`, `.document()`, `.audio()`, `.from_path()`,
896
- `.from_url()`, `.from_bytes()`) and a `media=[...]` argument on
897
- `AgentRunner.invoke` / `stream` and `AsyncAgentRunner.ainvoke` /
898
- `astream`. Items can be paths, URLs, `Media`, or content-part dicts
899
- in either provider's native shape; each model renders them in its
900
- own wire format (OpenAI `image_url` / `file` / `input_audio`,
901
- Anthropic `image` / `document`). Unsupported combinations -- audio to
902
- Claude, a document URL to GPT -- raise `ValueError` before any
903
- request. Media is stored as plain JSON dicts, so `completion.history`
904
- and `Session.save()` keep working. Guide: docs/guides/media.md.
905
-
906
- - **Models adapt to per-generation parameter support.** `GPT` and
907
- `Claude` read a parameter-compatibility 400 (which names the
908
- parameter and, for enums, the allowed values), make the smallest
909
- change it asks for, retry, and remember it per model: an unsupported
910
- `reasoning_effort` moves to the nearest supported value, `max_tokens`
911
- becomes `max_completion_tokens` on reasoning models (up front for
912
- known families), parameters a model lacks are dropped, and Claude's
913
- `max_tokens` is clamped to the model's cap. Logged at WARNING; other
914
- 400s raise unchanged. `adapt_params=False` opts out.
915
-
916
- - **`Claude` gains `top_p`, `top_k`, `thinking`, `stop_sequences`.**
917
-
918
- ### Changed
919
-
920
- - `Claude(temperature=)` defaults to `None` (not sent; the API default is
921
- the old 1.0). Always sending it conflicted with `top_p` on newer models
922
- and with extended thinking.
923
- - `GPT(reasoning_effort=)` accepts any string, not just
924
- `none | low | medium | high`, so `minimal` and `xhigh` are expressible.
925
-
926
- ### Fixed
927
-
928
- - **`reasoning_effort="none"` crashed on models that don't take it**
929
- ("Unsupported value: 'reasoning_effort' does not support 'none' with
930
- this model"). The models docs even recommended `"none"` as a fix for
931
- tool-calling conflicts; that advice is gone.
932
- - **Workspace-rooted paths resolved to the drive root.** With a workspace
933
- set, `/bruce.jpeg` became `C:\bruce.jpeg` on Windows (a leading slash
934
- with no drive means the current drive's root) and the sandbox rejected
935
- it. A leading slash now means the workspace root; the re-rooted path
936
- is still sandbox-checked, so traversal is rejected as before.
937
- - **`run_python` ran in the host process's directory, not the
938
- workspace.** It passed no `cwd`, so `open("bruce.jpeg")` looked
939
- wherever the program was launched from. It now starts in the workspace,
940
- matching `run_shell`.
941
- - **Message-list input stringified media into the prompt.** A user turn
942
- whose content was a list (text + image) went through `str()`, so an
943
- attached image reached the model as base64 text. Text and media are
944
- now split, and earlier turns keep their list content.
945
- - **Claude returned the wrong block with extended thinking.** It read
946
- `response.content[0].text`; with thinking the first block is a
947
- `thinking` block. Text blocks are now joined.
948
- - `GPT.Initialize` / `stream_text` / `astream_text` now run messages
949
- through the same OpenAI translator as `call_with_tools`.
950
-
951
- ## [3.3.1] - 2026-09-09
952
-
953
- Correctness fixes in the agent loop, found by driving it with a
954
- scripted model rather than reading it. No API changes; every fix
955
- replaces a silent wrong answer or a runaway cost with correct
956
- behaviour. Nine regression tests ship with them
957
- (`tests/test_agent_loop_flaws.py`).
958
-
959
- ### Fixed
960
-
961
- - **Native binding had no loop-level spiral guard.** The repeat breaker
962
- sat after the native branch's `continue`, so `bind_tools_natively`
963
- runs never reached it: a model stuck re-issuing one call burned the
964
- full `max_iterations` (20 LLM turns where text mode stopped at 3) and
965
- returned the "hit max_iterations" recap quoting the dup-guard's own
966
- warning text instead of the data.
967
-
968
- - **`respond` batched with real tool calls dropped them.** A model that
969
- emitted "do X, and here is my answer" in one turn had X silently
970
- discarded -- never dispatched, never in `completion.tool_calls`, no
971
- error. The batch now runs and the answer defers one turn.
972
-
973
- - **`completion.history` could not be replayed as `chat_history`.** The
974
- copy filter kept only truthy `{role, content}`, which dropped every
975
- tool-calling assistant turn (`content=""`), stripped `tool_call_id`
976
- off `role="tool"` messages, and replayed a stored system prompt on top
977
- of the fresh one -- so a follow-up call sent two system messages, zero
978
- assistant turns, and an orphaned tool message providers reject. Fixed
979
- in both runners.
980
-
981
- - **A sync `AgentRunner` silently ignored async tools.** `known_tools`
982
- unioned only the two sync registry tables while the registry accepted,
983
- listed and prompt-advertised async ones, so calling one fell through
984
- to implicit-final and returned `action_input` as the answer with an
985
- empty `tool_calls` list. Now unions all four, matching the async
986
- runner; the sync dispatcher already returns a clear `ToolError`, so
987
- the silent wrong answer became an actionable one.
988
-
989
- - **`AsyncAgentRunner` regressed the function-calling message shape.**
990
- It appended its FC turn as raw JSON text with no `tool_calls` block
991
- and never set `_last_function_call_id`, so observations went back as
992
- `role="user"` -- text-mode shape while in FC mode, losing provider
993
- correlation and the cached prefix.
994
-
995
- - **A `BaseException` from a specialist orphaned its siblings.**
996
- `CancelledError` and `KeyboardInterrupt` are not `Exception`, so
997
- `_run_subtask`'s handler never saw them; `t.result()` re-raised and
998
- left sibling tasks running unowned, with in-flight LLM calls still
999
- billing. The scheduler now owns its tasks in a `try`/`finally`, which
1000
- also covers a consumer that stops iterating `astream` early.
1001
-
1002
- - **The tool cache collided on tool name.** It is a process-wide
1003
- singleton keyed on `(tool_name, args)` with no record of which
1004
- implementation ran, so two runners whose tools merely share a name --
1005
- `search`, `fetch`, `query`, routine across Supervisor specialists --
1006
- served each other's results and the second function never ran. Keys
1007
- now fold in the callable's `module.qualname`, so same-name /
1008
- different-implementation misses while genuinely identical tools still
1009
- share, including across processes for the disk-backed `FileCache`.
1010
-
1011
- ### Docs
1012
-
1013
- - Streaming documentation described parameters the API rejects.
1014
- `AsyncAgentRunner.astream()` and `HandoffCoordinator.stream()` take no
1015
- `stream_tokens` (only the sync `AgentRunner.stream()` does), and every
1016
- `text_delta` example was built on a default model where
1017
- `use_function_calling` auto-detects to `True` and yields zero deltas.
1018
- `simple_stream` was documented with the wrong signature entirely.
1019
- Added a table naming exactly which stream methods accept what.
1020
-
1021
- ### Tests
1022
-
1023
- - Repaired 20 stale text-mode tests. `MockModel` defined
1024
- `call_with_tools` unconditionally, so 3.1.7's auto-detect routed every
1025
- text script down the function-calling path and the runner returned
1026
- `""`. The mock now advertises the capability only when scripted for
1027
- it. Suite: 206 passed, 3 skipped.
1028
-
1029
- ## [3.3.0] - 2026-08-19
1030
-
1031
- Dependency DAGs for the Supervisor. Plans declare which steps consume
1032
- which, and the executor derives ordering, parallelism, AND context
1033
- routing from those edges — unifying the old split where sequential
1034
- mode had threading but no parallelism and concurrent mode had
1035
- parallelism but no threading. Design: docs/design/3.3-depends-on-dag.md.
1036
-
1037
- ### Added
1038
-
1039
- - **`depends_on` plan steps.** Every plan step now carries an `id`;
1040
- a step that consumes an earlier step's output lists that id in
1041
- `depends_on`. Sync `Supervisor` executes in stable topological
1042
- order; `AsyncSupervisor` runs a completion-driven scheduler where a
1043
- step starts the MOMENT its dependencies finish (not on wave
1044
- barriers) and independent steps run concurrently. In DAG mode each
1045
- step is threaded ONLY its direct dependencies' results — explicit
1046
- routing instead of "everything prior", which also stops the
1047
- per-entry context budget shrinking as plans grow.
1048
-
1049
- - **Plan sanitization that never fails a run.** Missing/duplicate ids
1050
- auto-assigned, unknown dependencies dropped (a planner typo degrades
1051
- to a root step, not a dead run), self-deps dropped, cycles broken
1052
- deterministically (back-edge in plan order), spawn steps cannot be
1053
- depended on. If repairs were needed, the plan is re-requested once
1054
- (`max_plan_retries`, default 1) with the repair warnings appended;
1055
- the sanitized original is kept when the retry is no better.
1056
-
1057
- - **Failure cascade + `skipped` flag.** A step whose dependency failed
1058
- (after retries / success-check) is skipped, transitively, with
1059
- `SubtaskResult.skipped=True` and an error naming the failed dep.
1060
- Independent branches keep running; synthesis runs over what
1061
- succeeded. Skipped steps never dispatch — no tokens burned
1062
- downstream of garbage.
1063
-
1064
- - **`skip_when` conditional execution.** A step may declare
1065
- `{"step": <direct dep id>, "field": <typed output field>, "is": <value>}`;
1066
- evaluated in Python (no LLM call) against the dependency's 3.2
1067
- structured output, dotted paths supported, strictly FAIL-OPEN (any
1068
- doubt → the step runs). Condition-skips do NOT cascade — dependents
1069
- treat them as empty successes ("retrieval unnecessary" is not
1070
- "answering impossible").
1071
-
1072
- - **`Specialist` registry entries.** `agents={}` now also accepts
1073
- `Specialist(description, runner, depends_on=[...names...],
1074
- output_schema=..., when_to_use=...)`. The extras render into the
1075
- planning catalog (`typically after:` / `returns: Schema(fields)` /
1076
- `use when:`) so the planner can write real dependency graphs and
1077
- `skip_when` conditions against actual field names. `depends_on`
1078
- here is a planner HINT, never an execution constraint (the same
1079
- specialist can appear twice in one plan; step-ids disambiguate).
1080
- Classic `(description, runner)` tuples keep working — they are
1081
- wrapped internally, and `Specialist` tuple-unpacks for older code.
1082
-
1083
- - **`AsyncSupervisor(max_parallel=N)`.** Caps concurrent sub-tasks for
1084
- rate-limited deployments. `sequential=True` is now sugar for
1085
- `max_parallel=1` with all-prior threading.
1086
-
1087
- - **`SubtaskResult.step_id` / `.depends_on` / `.skipped`** and a
1088
- `step_id` field on `dispatch` / `subtask_result` stream events.
1089
-
1090
- ### Backward compatibility
1091
-
1092
- A plan where NO step declares `depends_on` runs with byte-identical
1093
- legacy semantics: sync + async-sequential thread all prior results in
1094
- plan order; async-concurrent runs everything at once with no
1095
- threading. Verified by regression tests against the 3.2 behaviour.
1096
-
1097
- ## [3.2.0] - 2026-08-13
1098
-
1099
- Typed multi-agent pipelines. Specialists can now declare a Pydantic
1100
- output schema once and pass validated instances to each other through
1101
- the Supervisor, instead of downstream agents re-parsing prose.
1102
-
1103
- ### Added
1104
-
1105
- - **`output_schema` on the `AgentRunner` / `AsyncAgentRunner`
1106
- constructor.** Declare the runner's output shape once
1107
- (`AgentRunner(..., output_schema=QueryIntent)`) instead of passing it
1108
- on every call or describing JSON in the prompt. A per-call
1109
- `output_schema=` still wins when both are set. `None` keeps the exact
1110
- pre-3.2 behaviour: no coercion, `completion.output` stays `None`.
1111
-
1112
- - **Schema coercion via forced native function calling.** When a schema
1113
- is in play, the final answer is converted by forcing a provider-native
1114
- tool call against the schema (constrained decoding), not by regexing
1115
- JSON out of prose. The ReAct loop itself is untouched: tool selection
1116
- and intermediate reasoning run exactly as before, and the coercion
1117
- happens once, after the loop finishes. Models without a
1118
- `call_with_tools` implementation fall back to the previous text-JSON
1119
- parsing, so custom `BaseChatModel` subclasses keep working.
1120
- `completion.content` keeps the human-readable answer alongside
1121
- `completion.output` in every case.
1122
-
1123
- - **`SubtaskResult.output`.** The Supervisor now preserves each
1124
- specialist's validated Pydantic instance next to its `content` text.
1125
- Consumers that only read `content` are unaffected.
1126
-
1127
- - **Structured specialist-to-specialist handoff.** When an earlier step
1128
- produced typed output, `_build_augmented_query` serializes it into the
1129
- next specialist's context as a labelled JSON block
1130
- (`STRUCTURED OUTPUT (QueryIntent): {...}`) followed by the summary
1131
- text, so downstream steps parse fields rather than interpreting
1132
- sentences like `INTENT: ... SEARCH_QUERY: ...`.
1133
-
1134
- - **`vector_search_tool` pipeline options.** New kwargs:
1135
- `max_text_chars` (default 500; pass `0` for full untruncated passages,
1136
- which a reranker judging evidence actually needs) and
1137
- `structured_output` (default False; when True the tool returns a JSON
1138
- array of `{id, text, vector_score, metadata}` instead of the
1139
- human-formatted list). Defaults preserve existing behaviour byte-for-
1140
- byte.
1141
-
1142
- ### Fixed
1143
-
1144
- - **Supervisor planning prompt contradicted the execution engine.** The
1145
- planner rule said sub-agents "do NOT see previous steps' output" and
1146
- discouraged dependency chains, but the dispatcher has threaded prior
1147
- findings into every step since `_build_augmented_query` shipped.
1148
- The rule now tells the planner that sequential steps receive earlier
1149
- results (structured when available) and that chains like
1150
- intent -> retrieval -> reranking are a good plan shape, while still
1151
- requiring same-specialist steps to merge and banning report-only steps.
1152
-
1153
- ## [3.1.7] — 2026-07-27
1154
-
1155
- ### Changed
1156
-
1157
- - **`use_function_calling` default flipped to auto-detect** on
1158
- `AgentRunner` / `AsyncAgentRunner`. The parameter's default type is
1159
- now `Optional[bool] = None`; `None` resolves to `True` when the
1160
- model class overrides `BaseChatModel.call_with_tools` (both `GPT`
1161
- and `Claude` do) and to `False` when it doesn't (or when
1162
- `bind_tools_natively=True`). Callers passing `True`/`False`
1163
- explicitly are unaffected. Rationale: text-mode ReAct requires the
1164
- model to emit strict JSON with any long `action_input` string
1165
- properly escaped — a 1200-word markdown draft with unescaped
1166
- newlines or quotes reliably breaks `json.loads` and killed the run.
1167
- Function-calling mode routes the parser through the SDK's typed
1168
- channel so escaping is handled automatically. The historical
1169
- default (`False`) was the fragile option; the new default matches
1170
- what most users actually want.
1171
-
1172
- ### Fixed
1173
-
1174
- - **Malformed parser JSON no longer crashes the run.** When the
1175
- text-mode assistant response failed `json.loads` (typically because
1176
- a long `action_input` string had unescaped `"`, `\n`, or backticks),
1177
- the framework used to raise `JSONDecodeError` and unwind the whole
1178
- invocation. The runner now (1) tries a regex-based salvage that
1179
- extracts `{Thought, action, action_input}` from the raw text
1180
- covering the common "outer envelope valid, inner string broke
1181
- escaping" failure, and (2) if salvage fails, feeds a targeted fix
1182
- hint back to the model (`"your last response was not valid JSON;
1183
- emit …, escape newlines as \n"`) and continues the loop bounded
1184
- by `max_iterations`. Exhaustion returns a clear framework message
1185
- rather than an uncaught exception. Applied to both sync and async
1186
- runners via a shared `_salvage_react_json` helper.
1187
- The salvager's action-name regex is intentionally strict
1188
- (`[A-Za-z_][A-Za-z0-9_.\- ]{0,79}`) so it can't hallucinate an
1189
- "action" out of an unrelated `"key":"value"` pair inside malformed
1190
- JSON.
1191
-
1192
- - **Verbose trace in `bind_tools_natively` mode now prints tool
1193
- name + args + response.** Previously native runs showed blank
1194
- `[tool.call.start]` / `[tool.call.complete]` pairs (the
1195
- observability layer fires them without the trace context), so you
1196
- couldn't tell which tool the model actually invoked or what came
1197
- back. The runner now prints `[tool] Invoking '<name>' with args:
1198
- <input>` and `[tool] Response: <preview>` (or `[tool] Error: ...`
1199
- when the dispatch raised) in the post-dispatch loop, matching the
1200
- format text-mode and function-calling mode use. Mirrored to the
1201
- async runner.
1202
-
1203
- - **`web_fetch_tool(vector_store=...)` auto-ingests fetched pages into
1204
- a vector store** instead of dumping raw HTML into the model's
1205
- context. Fixes the TPM-limit trap: when a research agent fetches
1206
- four articles in parallel (via ``multi_tool_use.parallel`` or
1207
- native binding), the combined bodies can easily exceed 40k tokens
1208
- and blow past a 30k TPM ceiling on the very next model call.
1209
- New parameters on ``web_fetch_tool``:
1210
-
1211
- | Kwarg | Default | Effect |
1212
- |---|---|---|
1213
- | ``vector_store`` | ``None`` | When set, each fetch is HTML-stripped, chunked with ``TextSplitter``, embedded via the store's embeddings, and added with ``{src: url, chunk_index, total_chunks}`` metadata. The tool response becomes a compact summary (URL, byte count, chunk count, 240-char preview) — NOT the raw body. The model then calls ``vector_search`` / ``Rag`` to pull only the passages it needs. |
1214
- | ``chunk_size`` | ``1500`` | Characters per chunk when ``vector_store`` is set. Ignored otherwise. |
1215
- | ``chunk_overlap`` | ``200`` | Overlap between adjacent chunks so a fact spanning a boundary is still retrievable. Ignored otherwise. |
1216
-
1217
- Backwards-compatible: the positional ``cache_dir`` signature keeps
1218
- working; `web_fetch_tool()` with no ``vector_store`` returns raw
1219
- body as before. Ingest and cache_dir compose — enable both and get
1220
- disk-cached full bodies AND searchable chunks. HTML stripping is
1221
- minimal and dependency-free (regex-based: script/style blocks
1222
- dropped whole, then tags stripped, whitespace collapsed) so the
1223
- ingest path adds no new install dependency. On JSON/plain-text
1224
- responses the stripper is a near no-op.
1225
-
1226
- The observation returned to the model shows topical coverage --
1227
- first, middle, and last chunk previews (up to 3 samples,
1228
- deduplicated for short pages) -- so the model can tell what
1229
- topics the page actually covers, not just the intro paragraph.
1230
- Without this the model would only see the page's opening and
1231
- wouldn't know to query for topics discussed later in the same
1232
- page. Explicit instruction in the observation ("query with
1233
- SPECIFIC keywords from the topics above; do NOT re-fetch; do
1234
- NOT ask for the full body") steers the model toward the RAG path
1235
- on follow-up turns.
1236
-
1237
- - **`multi_tool_use.parallel` now reaches its dispatch path.**
1238
- When GPT wanted to batch several tool calls into one turn (fetch N
1239
- URLs concurrently, run M searches at once), it emitted OpenAI's
1240
- synthetic `multi_tool_use.parallel` meta-tool. The registry's
1241
- `_dispatch_multi_parallel` / `_adispatch_multi_parallel` handlers
1242
- already knew how to unpack it, but the runner loop's known-tools
1243
- guardrail rejected the name FIRST as unregistered — dumping the
1244
- raw `{"tool_uses": [...]}` payload into the user-facing "final
1245
- answer" and never invoking any of the nested calls. Added
1246
- `multi_tool_use.parallel` to the recognized action set in both
1247
- sync and async runners so the meta-tool flows through to dispatch
1248
- and the existing unpackers run. Nested calls with the `functions.`
1249
- prefix are normalized before dispatch (same as top-level FC
1250
- calls), so the model can emit either shape.
1251
-
1252
- - **`Permissions.full_access` / `read_only` auto-wrap a bare string.**
1253
- Passing `full_access("./workspace")` used to iterate the string
1254
- into 11 single-character "subtrees" (Python's `list("./workspace")`)
1255
- — every path check silently rejected because no real path could
1256
- ever match a `"."` or `"/"` "allowed subtree". The classmethod
1257
- now detects a bare string and treats it as `[allowed_paths]`, so
1258
- `full_access("./workspace")` does the intuitive thing (equivalent
1259
- to `full_access(["./workspace"])` and auto-infers the workspace).
1260
- Same fix on `read_only`. List inputs are unchanged.
1261
-
1262
- - **`Permissions.full_access` now accepts (and auto-infers)
1263
- `workspace`.** The classmethod set `allowed_paths` but not
1264
- `workspace`, so short paths like `write_file(path="report.md")`
1265
- resolved to CWD (outside the sandbox) and raised
1266
- `PermissionError: access denied` — a landmine that every caller of
1267
- `Permissions.full_access(["./workspace"])` hit sooner or later.
1268
- New signature: `full_access(allowed_paths, *, workspace=None)`.
1269
- When `workspace` isn't passed AND `allowed_paths` has exactly one
1270
- entry, that path is auto-set as the workspace (the "project-scoped
1271
- agent whose one allowed subtree IS its workspace" case, which is
1272
- 99% of use). Two or more paths stay ambiguous and require an
1273
- explicit `workspace=` if short-path resolution is wanted. Pass an
1274
- explicit `workspace=` string to override the auto-choice.
1275
- Backwards-compatible on the positional signature; adds a keyword
1276
- argument that existing callers didn't use.
1277
-
1278
- ## [3.1.5] — 2026-07-26
1279
-
1280
- ### Fixed
1281
-
1282
- - **Text-mode tool results no longer use `role: "function"`.** In text
1283
- mode (the default — no `use_function_calling`) the runner fed each tool
1284
- observation back to the model as a `role: "function"` message. Newer
1285
- OpenAI models reject that role outright (`400 … 'messages[N].role' does
1286
- not support 'function' with this model`, e.g. gpt-5.x), and Anthropic
1287
- never accepted it — text-mode multi-tool runs on Claude were latently
1288
- broken too; older GPT models simply still tolerated the legacy role.
1289
- Tool observations now go back as a plain `role: "user"` turn framed as
1290
- `Observation: …`, which every provider and model generation accepts and
1291
- which matches the ReAct template's own few-shot convention.
1292
- Function-calling mode is unchanged (native `role: "tool"` +
1293
- `tool_call_id`). The async runner was additionally emitting `function`
1294
- unconditionally (even in FC mode); it now uses the same shared helper.
1295
-
1296
- ### Added
1297
-
1298
- - **`subtask_success_check` on `Supervisor` / `AsyncSupervisor`.** Opt-in
1299
- predicate `(SubtaskResult) -> bool | str` that decides whether a
1300
- *returned* (non-raised) sub-task result is actually acceptable — the
1301
- "ran fine but produced nothing useful" case a plain retry can't catch
1302
- (a scraper that saved 0 links, an extractor that found nothing). Return
1303
- `True` to accept, or `False`/a `str` reason to reject; a rejected
1304
- result is retried like a raised error, with the reason fed back into the
1305
- query, bounded by `max_subtask_retries`. After retries are exhausted the
1306
- last result is returned with its `error` set (content preserved). A
1307
- check that itself raises is treated as "accept" so a buggy predicate
1308
- can't wedge the run. Default `None` keeps the exceptions-only behavior.
1309
- New example `examples/robust_link_scraper.py` wires it together with a
1310
- scraping `system_addendum` (parse relative+absolute hrefs, fall back to
1311
- `sitemap.xml` on JS-rendered sites).
1312
-
1313
- ## [3.1.4] — 2026-07-26
1314
-
1315
- ### Fixed
1316
-
1317
- - **A malformed-JSON tool argument no longer crashes the whole agent
1318
- run.** When a model emitted a Python snippet or a Windows path as a
1319
- tool-call argument — `re.findall(r'\d+')`, `C:\Users` — the `\d` / `\U`
1320
- are illegal JSON escapes, and the OpenAI adapter's eager
1321
- `json.loads(call.function.arguments)` raised `JSONDecodeError` and
1322
- `raise`d it, unwinding the entire ReAct loop before the agent's own
1323
- retry machinery could act. Under a Supervisor this surfaced as a bare
1324
- `ERROR: Invalid \escape: line 1 column 598` and the sub-task was
1325
- abandoned. Now:
1326
- - `_parse_tool_arguments` repairs the common case (backslashes that
1327
- don't begin a valid JSON escape are doubled), recovering `\d`,
1328
- `\w`, `\s`, etc. with zero extra round-trips. A backslash before a
1329
- valid-escape letter (`\b`, `\n`, …) remains ambiguous and is left
1330
- as the escape — a documented limit.
1331
- - When repair fails, `call_with_tools` returns a dedicated
1332
- `invalid_tool_args` result and the loop feeds the error back as a
1333
- retryable observation ("your arguments weren't valid JSON — escape
1334
- backslashes and resend"), bounded by `max_iterations`, in all
1335
- three modes across both `AgentRunner` and `AsyncAgentRunner`.
1336
- `Claude` was already immune (its tool inputs arrive pre-parsed).
1337
-
1338
- - **A tool-call preamble is no longer returned as the final answer.**
1339
- Models routinely end a turn with an announcement instead of an action
1340
- — "I'll look up your recent scores to get a clear view of your
1341
- communication skills. Just a second!" — and every "no tool call
1342
- found" branch in both runners was coded as *this text is the answer,
1343
- break*. The loop terminated on iteration 1 and the caller got a
1344
- promise instead of a result. Three sites per runner were affected:
1345
- the native-binding path (`type != "tool_use"`), the
1346
- `use_function_calling` path (parser unresolved), and the JSON-text
1347
- path (response didn't parse). `max_iterations` never helped, because
1348
- the break happened before any iteration was spent.
1349
-
1350
- The runner now feeds the model one corrective nudge — "your last turn
1351
- had no action, so nothing happened; do it, don't announce it" — and
1352
- continues the loop. Verified against both `AgentRunner` and
1353
- `AsyncAgentRunner` in all three modes.
1354
-
1355
- ### Added
1356
-
1357
- - **Proactive "act, don't announce" system-prompt clause.** The reactive
1358
- `text_turn_nudges` fix corrects an agent *after* it narrates instead of
1359
- acting; this clause heads it off. When (and only when) an agent has
1360
- tools, its system prompt now tells it to call the tool rather than
1361
- reply "I'll do X / just a second" and stop — and to report what it DID
1362
- in past tense. Injected in all three modes across both runners; skipped
1363
- for tool-less chat agents, where prose is the correct answer. Sits
1364
- before any `system_addendum` so a caller's role instructions still win.
1365
-
1366
- - **`max_subtask_retries` on `Supervisor` / `AsyncSupervisor`** (default
1367
- `1`). A sub-task that raised used to be recorded as an error and the
1368
- Supervisor moved straight to synthesis — no second attempt. Now a
1369
- failed sub-task is re-dispatched up to this many times, with the prior
1370
- error appended to the query so the specialist knows what to fix
1371
- ("your previous attempt failed with X — diagnose and try again").
1372
- Bounded and informed: only raised exceptions trigger a retry (a
1373
- sub-task that returns content is accepted as-is, since the Supervisor
1374
- can't tell "terse but correct" from "wrong"), and the error text is
1375
- fed back rather than blindly re-running. Set to `0` for the old
1376
- quit-on-first-failure behavior. Applies in both sequential and
1377
- concurrent async modes.
1378
-
1379
- - **`text_turn_nudges` on `AgentRunner` / `AsyncAgentRunner`** (default
1380
- `1`). Caps the re-prompts described above at one extra LLM call per
1381
- run; after the budget is spent the model's text stands as the answer.
1382
- Set to `0` for the previous behavior. Automatically skipped when no
1383
- tools are registered, since a runner with no tools is a plain chat
1384
- call and prose genuinely is the answer there.
1385
-
1386
- ## [3.1.3] — 2026-07-22
1387
-
1388
- Docs-only patch. No code changes since 3.1.2. Users on 3.1.2 don't
1389
- need to upgrade for functionality; upgrade to pick up the improved
1390
- onboarding docs bundled in the sdist.
1391
-
1392
- ### Documentation
1393
-
1394
- - **Tools doc rewritten to answer "how do I actually use these?"**
1395
- Added §0 `How each built-in tool is registered` as the entry
1396
- section. Two registration paths — auto vs manual — laid out in a
1397
- table on the first screen. Six runnable subsections covering every
1398
- combination:
1399
- - §0.1 DefaultTools via `Permissions(...)` (auto)
1400
- - §0.2 WebTools via `tools=[web_search_tool(), web_fetch_tool()]`
1401
- - §0.3 RAG via `TextSplitter` -> `VectorStore.add_documents` ->
1402
- `vector_search_tool(store)`
1403
- - §0.4 Handoffs via `handoff_tool` + `HandoffCoordinator`
1404
- - §0.5 Custom `StructuredTool` from scratch
1405
- - §0.6 Fully-loaded runner combining all of the above
1406
- - §0.7 Rules on name collisions, invisible-denied-capabilities,
1407
- async-tool behavior
1408
- The existing inventory + wrapper / controls / cheat-sheet sections
1409
- are unchanged; they now sit after the "how to use them" primer
1410
- instead of before it.
1411
-
1412
- ## [3.1.2] — 2026-07-22
1413
-
1414
- Patch release. Two independent fixes.
1415
-
1416
- ### Fixed
1417
-
1418
- - **`llm_judge` correctly parses YES/NO across providers.** The judge
1419
- parser was comparing the reply's first word to the literal string
1420
- `"YES"`. GPT-4o answers `"YES,"` (comma-suffixed), which failed the
1421
- equality check and marked every genuine PASS as FAIL. Claude replies
1422
- `"YES"` without punctuation so the bug hid during local development.
1423
- Fixed by matching `\b(YES|NO)\b` (word-boundary regex, case-
1424
- insensitive) at the start of the reply. Handles every real shape:
1425
- `YES`, `YES.`, `YES!`, `YES, exactly right`, `Yes.`, `yes -- reason`.
1426
- Ambiguous replies (`Maybe`, empty string) still fail closed.
1427
- - Regression test `test_llm_judge_parses_various_verdict_shapes`
1428
- covers 8 YES shapes, 5 NO shapes, and 4 ambiguous replies.
1429
-
1430
- ### Added
1431
-
1432
- - **`agentx_dev.Tools` is a one-stop tools namespace.** Users no
1433
- longer need to remember which module each tool lives in:
1434
-
1435
- ```python
1436
- from agentx_dev.Tools import (
1437
- StandardTool, StructuredTool,
1438
- AsyncStandardTool, AsyncStructuredTool,
1439
- web_search_tool, web_fetch_tool,
1440
- vector_search_tool, handoff_tool,
1441
- DefaultTools, Permissions,
1442
- )
1443
- ```
1444
-
1445
- Both this form and the pre-existing `from agentx_dev import X`
1446
- form coexist. Implementation uses PEP 562 module `__getattr__`
1447
- and `__dir__` so re-exports are lazy (no import cost for modules
1448
- the caller doesn't touch) and show up in IDE autocomplete +
1449
- `dir(agentx_dev.Tools)`.
1450
-
1451
- ## [3.1.1] — 2026-07-21
1452
-
1453
- Second batch of 3.1 features + a full docs + brand pass.
1454
-
1455
- ### Added
1456
-
1457
- **Streaming through orchestration**
1458
- - `Supervisor.stream()` / `AsyncSupervisor.astream()` emit
1459
- `plan_start` / `plan` / `dispatch` / `subtask_result` /
1460
- `synthesize_start` / `final` / `completion` events.
1461
- - `HandoffCoordinator.stream()` / `.astream()` emit `invoke` /
1462
- `completion` / `handoff` / `final` / `result` events per hop.
1463
- - Legacy `.run()` / `.arun()` refactored to consume the streams (no
1464
- code duplication).
1465
-
1466
- **Prompt optimization — `Compiled`**
1467
- - New `agentx_dev.Compiler` module.
1468
- - `Compiled(runner_factory, trainset, ...)` iteratively refines a
1469
- runner's `system_addendum` against the eval harness. Half of
1470
- DSPy's power at a tenth of the surface.
1471
-
1472
- **Anthropic Batch API**
1473
- - `Claude.batch(requests)` submits many prompts at Anthropic's 50%-off
1474
- batch rate, polls to completion, returns results in submission order.
1475
- - Per-request error dicts on failure; token usage funneled into
1476
- `TokenUsage` so cost tracking stays a single source of truth.
1477
-
1478
- **Vector store adapters — `agentx_dev.VectorStores`**
1479
- - `ChromaVectorStore`, `QdrantVectorStore`, `PgVectorStore` — same
1480
- public shape as the in-memory `VectorStore` (`add` / `search` /
1481
- `delete` / `clear` / `__len__` / `embeddings`).
1482
- - `vector_search_tool()` and `SemanticMemory` accept any of them.
1483
- - SDK imports lazy; friendly `ImportError` when the underlying SDK
1484
- is missing.
1485
-
1486
- **Trace viewer (`viewer/`)**
1487
- - Self-hosted single-page app that reads `FileHook` JSONL and renders
1488
- a timeline with type/text filters, summary sidebar, JSON drill-down.
1489
- - Works from `file://`, no server required.
1490
-
1491
- **Docs site (`host/`)**
1492
- - Full editorial dark-first design system (JetBrains Mono headings,
1493
- Inter body, `#B8FF3E` electric-lime accent).
1494
- - Command palette (`Cmd+K`) with keyboard navigation and live search.
1495
- - Hero code snippet with hand-tinted syntax highlighting.
1496
- - Reading progress bar, breadcrumbs, header anchor links.
1497
- - Sidebar sliding active marker, collapsible groups.
1498
- - Code copy buttons, language labels.
1499
- - Right-rail auto-TOC with `IntersectionObserver` scrollspy.
1500
- - Dark/light theme toggle, persisted.
1501
- - Cache-busted assets so edits land on refresh without hard-reload.
1502
-
1503
- **Brand identity (`brand/`)**
1504
- - Full brand kit: 5 SVG assets (`mark`, `mono`, `wordmark`, `logo-full`,
1505
- `app-icon`), `BRAND.md` strategy doc, rendered brand-kit HTML deck.
1506
- - Copy audit dropped "small" (weak) and "LangChain" references from
1507
- all marketing surfaces.
1508
- - Favicon wired into docs + trace viewer.
1509
-
1510
- **Test suite (`tests/`)**
1511
- - Restored + expanded pytest suite: 127 tests passing (3 skipped for
1512
- absent optional SDKs).
1513
- - Coverage: parser + all `AgentType` variants, `ToolRegistry`
1514
- (dispatch / dup-guard / circuit-breaker / timeout), Permissions
1515
- (capability gating + sandbox + traversal), budgets (cost / rate /
1516
- retry / non-retryable HTTP), runner loop (streaming + output_schema
1517
- + chat history), embeddings + `VectorStore` + `SemanticMemory`,
1518
- handoffs (bounded hops + history sanitization), evals harness
1519
- (all assertion helpers + JSON case loaders), vector-store adapter
1520
- shape conformance.
1521
-
1522
- **Docs (`docs/`)**
1523
- - Full docs tree (34 pages), including new pages for:
1524
- vector store adapters, prompt optimization, batch API, trace viewer,
1525
- and a **use-cases** landing (13 concrete scenarios with runnable code).
1526
- - Rewrote **Tools** page to enumerate every built-in tool with args,
1527
- return shape, capability flag, and use-case guidance.
1528
- - Rewrote **Agents** page to cover all four orchestration
1529
- architectures (Solo / Supervisor / Handoffs / Compiled) with
1530
- decision trees, worked examples, and cheat sheet.
1531
- - **Agentic RAG chatbot** as use case §13 — multi-query decomposition,
1532
- parallel retrieval, self-critique, citations, user memory.
1533
-
1534
- **Examples**
1535
- - `examples/agentic_rag_demo.py` — the runnable version of the
1536
- agentic RAG use case. Auto-seeds a KB if none exists, `--demo` flag
1537
- runs a 3-turn scripted session proving user-notes recall works.
1538
-
1539
- **Package**
1540
- - `[chroma]`, `[qdrant]`, `[pgvector]`, `[dev]` extras added.
1541
- - `[anthropic]` bumped to `>=0.36` (Batch API + prompt cache).
1542
-
1543
- ### Fixed
1544
-
1545
- - `AgentRunner._iter_run` in `bind_tools_natively=True` mode uses a
1546
- minimal system prompt instead of the AgentType template so the
1547
- ReAct `action/action_input` scaffold no longer fights the native
1548
- tool interface. Previously produced JSON-blob answers under GPT.
1549
- - `HandoffCoordinator._sanitize_history_for_next_agent` strips tool
1550
- and function role messages between hops so tool_call_ids from a
1551
- previous agent don't leak into the next model's call (OpenAI 400).
1552
- - Docs site marker positioning uses double-`requestAnimationFrame` +
1553
- `document.fonts.ready` so the sidebar accent bar lands on the
1554
- correct row even on a cold font cache.
1555
- - Primary hero CTA color uses `#doc .hero-cta a.primary` selector to
1556
- outrank `#doc a` link styling (previously rendered lime-on-lime
1557
- and was invisible).
1558
-
1559
- ### Notes
1560
-
1561
- - Package version bumped from `3.0.6` to `3.1.1`. The 3.1.0 release
1562
- did not ship publicly — 3.1.1 is the first 3.1-tagged PyPI release
1563
- and includes both batches of features.
1564
-
1565
- ## [3.1.0] — internal only (commits 52840e7)
1566
-
1567
- First batch of 3.1 features. Committed but not released to PyPI.
1568
- Merged into 3.1.1 for the public release.
1569
-
1570
- ### Added
1571
- - Anthropic prompt caching (`Claude(enable_prompt_cache=True)`).
1572
- - Parallel per-turn tool dispatch in `AgentRunner`
1573
- (`bind_tools_natively=True`, `parallel_tool_workers`).
1574
- - Semantic memory (`SemanticMemory`, embeddings-backed retrieval).
1575
- - RAG core (`Embeddings`, `HashEmbeddings`, `OpenAIEmbeddings`,
1576
- `VectorStore`, `VectorHit`, `vector_search_tool()`).
1577
- - Agent-to-agent handoffs (`HandoffRequest`, `handoff_tool`,
1578
- `HandoffCoordinator`, `HandoffResult`).
1579
- - Evals harness (`EvalCase`, `EvalRunner`, `EvalReport`, 7 assertion
1580
- helpers, JSON case loader, `python -m agentx_dev.Evals run` CLI).
1581
- - `TokenUsage.cache_hit_ratio` property.
1582
-
1583
- ## [3.0.6] — 2026-03 (baseline)
1584
-
1585
- Security hardening baseline (SSRF guard on `web_fetch`, HMAC-signed
1586
- persistent state, scrubbed subprocess env, path sanitizer,
1587
- `permissions.json` mode 0o600, ReDoS guard on `grep`,
1588
- `invoke`/`ainvoke` accept bare strings and message lists).
1
+ # Changelog
2
+
3
+ All notable changes to `agentx-dev` are documented here. Format loosely
4
+ follows [Keep a Changelog](https://keepachangelog.com/); versioning is
5
+ [Semver](https://semver.org/).
6
+
7
+ ## [Unreleased]
8
+
9
+ ## [3.9.0] - 2026-11-16
10
+
11
+ ### Added
12
+
13
+ - **Two conversations side by side in the app window.** Drag a conversation from **Recent** onto the chat (or use
14
+ the button that shows on the row) and it opens on the right half of the window, beside the one you are in; the
15
+ folder menu's **Open a folder beside…** opens a new conversation in another project there. Each side is an
16
+ agentx of its own, with its own history, settings, approvals, orb and memory, so both can work at once; they use
17
+ the same API keys. Closing a side (its ✕) saves its conversation and ends its agentx. On a phone-sized window the
18
+ side covers the chat until you close it. Drag the line between the sides to give either one more room (double-click it
19
+ for half and half; the split is remembered). Each side's **Details** belongs to that side: the left one opens
20
+ beside the left conversation, not past the other side.
21
+ - **Details can be resized.** Drag its left edge to make the panel wider or narrower (from 260 pixels to 60% of
22
+ the window); the width is remembered, and a double-click on the edge puts it back. It works as a column, when it
23
+ slides over the chat, and on either side of the split view.
24
+
25
+ - **API keys in the app window.** Settings has an **API keys** tab: paste your Claude or OpenAI key to save it,
26
+ replace it later, or remove it. Keys are kept encrypted by your system's credential store (Windows Credential
27
+ Manager, the macOS Keychain, the Secret Service on Linux), never in a file, and the page shows only their last
28
+ four characters. A saved key wins over the environment variable; agentx switches to it at your next message and
29
+ keeps the conversation. `keyring` is now installed with agentx.
30
+
31
+ ### Changed
32
+
33
+ - **The agentx orb.** A sphere of lime dots now shows what agentx is doing in the app window (the terminal keeps
34
+ its spinner).
35
+ While it thinks, its surface bubbles, dots pushing out and settling back; while a step runs, rings of dots light
36
+ up and turn on their own axes in opposite directions; when a turn finishes it rests in a slow turn with a soft
37
+ glow ("Done" shows for a moment); while it waits for your answer it folds into a cube that turns slowly and breathes, a band of light
38
+ sweeping down it. In the window, a new
39
+ conversation shows it large under "What should we work on?"; once you write it moves to the top, large, with a
40
+ small pill under it naming what it shows (Thinking, the step it runs, Waiting for your answer, Done and how long
41
+ it took, then Ready), and stays there for the rest of the conversation. The large orb can be grabbed with the mouse and spun; let go and it keeps the flick's
42
+ momentum, then settles into its slow turn in the direction you threw it.
43
+ - **A tidier conversation in the app window.** The mode note ("Auto mode is on.") is now a small chip: hover it
44
+ to read what the mode allows, click it to open Details. MCP servers that need signing in are listed in Details
45
+ only, with a yellow dot on its button, instead of a notice in the conversation. A new conversation no longer
46
+ repeats the model, its maker and the mode under the question (the message box already shows the model and the
47
+ mode), which leaves room for a larger orb. Once you write, the agentx header box (version, model, folder) and the mode
48
+ chip are gone, and the line over the message box no longer repeats what the orb's pill says. A new conversation
49
+ shows the mode chip again.
50
+
51
+ ### Fixed
52
+
53
+ - **A conversation opened again shows what it did.** In the app window, steps that a model wrapped in its response
54
+ format (`React_`) showed as "React" rows with the tool's name, or its note, as text; they now read as the tool
55
+ they ran (Run, Edit, Read...), with its note and the final answer. Details counts the tokens of the whole
56
+ conversation, across every start: a conversation's saved total was replaced by the last start's count each
57
+ turn, so an old one showed zeros or too little; it now adds up (tokens from the cache too). And Details lists the
58
+ team jobs a conversation ran before: each job now names its conversation in `job.md`, and an older one is matched
59
+ by its task (or, when the history has been summarised since, by when it ran).
60
+ - **An MCP sign-in in the app window.** `/mcp login` showed the whole sign-in address as text while the orb said
61
+ "Ready". It is now a small card with an **Open the sign-in page** button, and the orb folds into its cube with
62
+ "Waiting for you to sign in to <server>" until the sign-in ends (Esc cancels it).
63
+ - **A wider conversation in the app window.** The conversation and the message box use up to 1000 pixels instead
64
+ of 768, so a wide window has less empty space on each side.
65
+ - **Esc stops agentx in the app window while you type.** "Esc to stop" did nothing while the cursor was in the
66
+ message box; now it stops the turn from there too (what you typed stays), and the orb's pill reads "Stopping…"
67
+ until the turn ends. A stop during the pause before a model request is sent again (a rate limit asks for seconds)
68
+ now lands at once, instead of after the pause.
69
+
70
+ ## [3.8.1] - 2026-11-13
71
+
72
+ ### Changed
73
+
74
+ - **The app window opens like the docs site.** The mark rises with a soft glow, `agentx` types itself in letter by
75
+ letter and a lime cursor keeps blinking after it; "Starting..." (dots lighting up in turn) shows until agentx is
76
+ ready, and the welcome grows out of it. While it works, that blinking cursor replaces the round spinner.
77
+ - **The folder trust question highlights "No, exit".** Enter alone now exits; trust a folder with `1`, `y`, or Up
78
+ then Enter. The app window's trust card does the same.
79
+ - **"Don't ask again" is `2` in approval menus.** The `a` shortcut is gone from the arrow-key menu (it still works in
80
+ the typed `[y/a/n]` prompt), so a word typed for the chat cannot pick it.
81
+ - **Menus wait a moment before they take keys.** Keys typed before a menu appeared are thrown away, and keys pressed
82
+ in its first 0.4 seconds are ignored (Ctrl+C still cancels). In full-screen mode a menu waits while the input line
83
+ holds text (`Clear or send your message to answer`); keys keep editing the message and Enter sends it.
84
+ - **App window cards do not take the focus while you type.** When the message box holds text, or another field has
85
+ the focus, a new card leaves the focus where it is; from an empty message box `1`, `2`, `3` answer it but Enter and
86
+ Space do not.
87
+ - **Some granted commands ask again.** A "don't ask again" command grant no longer covers a call that uses an option
88
+ through which the program runs another program (`git fetch --upload-pack`, `make -f`, `rg --pre` and similar), and
89
+ `find`, `sed`, `tar`, `rsync`, `vim`, `git submodule`, `git rebase` and similar are never remembered.
90
+ - **An MCP server launcher that exists only as a `.ps1` script needs its full path.** A bare `"command"` is now looked
91
+ up on `PATH` only; one not found reads `not connected: <name> not found on PATH`.
92
+ - **A parent folder's `AGENTX.md` needs that folder trusted.** To use a repository's top-level file when you start
93
+ in a subfolder, trust the top folder once.
94
+
95
+ ### Fixed
96
+
97
+ - **`--remote` on a VPS prints the ssh command that works.** It assumed SSH on port 22 and guessed the address, so
98
+ a server on another port (2222, say) timed out. In an SSH session agentx now uses the address and port that
99
+ session came in on (`ssh -p 2222 ...`).
100
+
101
+ ### Security
102
+
103
+ - **Keys typed for the chat never answer an approval.** Keys still waiting when a prompt opens go to your message
104
+ line, never to the prompt; menus throw away keys typed before they appeared and ignore the first 0.4 seconds.
105
+ - **A stray Enter never trusts a folder.** The trust question opens on "No, exit", and keys typed while agentx
106
+ started are thrown away.
107
+ - **A command grant cannot approve another program.** "Don't ask again" on a command no longer approves a later call
108
+ that runs another program through its options (`git fetch --upload-pack`, `git grep -O`, `git -c`, `make -f` or
109
+ `VAR=value`, `go test -exec`, `cargo --config`, `rg --pre`, `npm --script-shell`) or holds `$ * ? [ {` for such a
110
+ program. Programs that run others through their options or scripts (`find`, `sed`, `tar`, `rsync`, `scp`, `zip`,
111
+ `vim`, `parallel`, `crontab`, `at`...) and git sub-commands such as `submodule`, `rebase`, `difftool`, `config` and
112
+ `hook` are approved once and never remembered.
113
+ - **An edit grant covers edits only.** Answering "don't ask again" at an edit prompt no longer lets web searches and
114
+ page fetches run unasked; they still ask until you choose `accept-edits` yourself or allow the web at a web prompt.
115
+ - **`/clear` and `/resume` also end a web "don't ask again" grant.**
116
+ - **The approval diff shows every hidden line break.** Lines split at LF only: a line break swapped for a form feed,
117
+ a vertical tab, U+2028 or a lone CR shows as a changed line with an escape such as `\x0c`, not as "only line
118
+ endings change".
119
+ - **Backslash paths on Linux and macOS.** A backslash is part of a file name there, so the deny rules (and the
120
+ prompt) also judge the file the name really reaches: a link named `x\y` cannot lead past the `.git` protection.
121
+ - **The window's key is never on a command line.** The window agentx opens gets a one-time start link (`?c=`) that
122
+ works once, for 2 minutes; the page trades it for the key. A second use is refused, the key is changed and the
123
+ terminal prints a warning with the new link.
124
+ - **An approval too long to show in full is declined.** A card whose action, target or preview would be cut is
125
+ declined without asking, with a notice saying why; "don't ask again" is not offered for a rule too long to show.
126
+ - **Links in answers cannot add attributes.** A link's address ends at a space, `(`, `)` or a quote, and each link is
127
+ built once, so model text cannot break out of it.
128
+ - **Saving Settings keeps declined project rules off.** Project allow rules you turned down at start, and rules added
129
+ to the project file since, stay off for the session after the window saves the settings.
130
+ - **Open another folder imports nothing from that folder** before the new agentx asks whether you trust it.
131
+ - **Pictures are never saved through a planted link.** When the project's `.agentx` or `.agentx/uploads` is a link,
132
+ a picture goes to `~/.agentx/uploads/`; the message names where the file really is.
133
+ - **Turning remote control off closes the windows opened through Tailscale** (their conversations are saved), and
134
+ the 30-second re-share check can no longer share the window again afterwards. agentx also changes its key, so a
135
+ link shared with another device stops working; windows on this computer get the new key and keep going.
136
+ - **Nothing is started from the project folder on Windows.** `run_shell` takes git-bash from Program Files, a
137
+ per-user Git install or `PATH` without the current folder, else System32's PowerShell; stopping a command runs
138
+ System32's `taskkill`; Tailscale, Edge, Chrome and PowerShell for the app window are found the same way.
139
+ - **MCP stdio servers' bare commands are found on `PATH` only**, never in the project folder (the server still
140
+ starts in the current folder).
141
+ - **Read-only auto-allows are re-checked on every connect.** Tools allowed because the server marked them read-only
142
+ are kept in `"auto"` in `mcp.json`, apart from your own `/mcp allow` choices; one the server stops marking read-only
143
+ asks again, with a warning. On the first connect after upgrading, saved `"allow"` entries the server marks
144
+ read-only move to `"auto"`.
145
+ - **A sign-in is tied to the server's address.** When a server's URL changes, the old sign-in is deleted instead of
146
+ being sent there; a server taken out of `mcp.json` is disconnected and its sign-in deleted; `/mcp add` under a
147
+ name used before starts signed out.
148
+ - **A parent folder's `AGENTX.md` is read only when you trust that folder.** The folder you start in and your home
149
+ folder's file are always read.
150
+ - **`grep` and `find_files` do not follow links out of the project.** A linked file that leads outside is skipped and
151
+ linked folders (Windows junctions included) are never entered.
152
+ - **`web_fetch` connects only to the address it checked**, on every redirect, so DNS rebinding cannot reach a local
153
+ address; a redirect to a private address reads `ERROR: refused`.
154
+ - **Saved conversations and their titles are readable by you only** (`0600`, new folders `0700`), and `~/.agentx` is
155
+ created yours only.
156
+ - **`/skills install` refuses a repository whose skill files have `:` in their paths** (another drive, or an NTFS
157
+ stream, on Windows) and never writes outside its download folder.
158
+
159
+ ## [3.8.0] - 2026-11-08
160
+
161
+ ### Added
162
+
163
+ - **One conversation per device in remote use.** Each device that opens the window (an iPad, a laptop, the
164
+ computer's own window) gets its own conversation and agent, with its own approvals, Stop and status, working at
165
+ the same time as the others in the same folder; before, every window shared one conversation, so a second
166
+ device's message slipped into the running task. The computer's conversation (the terminal's, or the first
167
+ window's) is listed on the others as **Live** and can be opened to share it, as before. `/exit` on a device ends
168
+ only its own; one unused for 15 minutes is put away and reopened when the device comes back; settings saved on
169
+ one device reach all; a window says when another conversation is working in the folder. Inside: each
170
+ conversation has its own team lane (a team job's questions, notes and `/skip` never reach another's), the
171
+ conversation titles, work log and team records take several writers, and one MCP sign-in runs at a time.
172
+ - **`agentx --ui`: the app window.** The same agentx in a desktop-style window instead of the terminal: the
173
+ conversations of the folder on the left (open one, or start a new one), your messages on the right, the agent's
174
+ steps as short rows (Read, Edit, Run, with look-around steps folded into one Explored row), answers rendered as
175
+ markdown, approvals as cards with the diff and Yes / don't ask again / No (with a reason) and keys 1-3, the other
176
+ questions as cards, the team's running steps, typed messages waiting with a button to take each back, and a
177
+ message box with the mode and model menus, `/` for commands and skills, a picture button (and paste or drop;
178
+ saved in `.agentx/uploads/`), a microphone button (`/voice`) and a send button that is Stop while it works.
179
+ It opens as an Edge or Chrome app window when one is installed, else in the browser. The app itself runs
180
+ unchanged; the window is another front end, served on 127.0.0.1 with a random token per start and a Host check.
181
+ `--port` and `--no-open`. No new packages.
182
+ - **The app window's side panel, Settings and remote use.** **Details** shows how full the conversation is, the
183
+ tokens used, the last team job step by step, the MCP servers by name with their own Sign in / Reconnect / Tools /
184
+ Sign out buttons, and the project memory. **Settings** saves the default model and mode, the allow and deny rules,
185
+ the steps and the token limit, for all folders or this folder (rules and limits apply at once). The **+** menu adds
186
+ a picture, mentions a file (search) or opens another folder in a new window. `agentx --ui --remote` keeps the window
187
+ on the server's 127.0.0.1 and prints the `ssh -N -L` command to use it from another computer. Light or dark follows
188
+ the system. A notice that MCP servers need sign-in has a button per server.
189
+ - **Remote control.** `/remote-control` in the terminal makes the running session usable from an iPad, a phone or
190
+ another computer: the terminal keeps showing everything, the window mirrors it, and messages, answers, menu choices
191
+ and approvals from the window go into the terminal's own prompt (the first answer wins). In the app window it adds
192
+ the remote ways to the window already served. With Tailscale on, `--remote` and `/remote-control` also listen on
193
+ the computer's Tailscale address (Tailscale devices only) and print a link for Safari; otherwise the SSH way. They
194
+ say when no SSH server runs, or when Windows Firewall blocks SSH on a Public network.
195
+ - **The model's thinking, shown.** On Claude Opus 5.5, Sonnet 5.5 and Fable 5.1 agentx asks for a readable summary of
196
+ the reasoning they do on every step anyway (`thinking.display: "summarized"`, same cost; nothing is sent back on
197
+ later requests), and on GPT reasoning models on the Responses API for OpenAI's reasoning summary (asked once more
198
+ only if the account allows it). The app window shows it, and the model's notes between steps, as Thinking blocks
199
+ as they happen, with a live Thinking… line; the terminal shows it before an edit or a command. In the library:
200
+ `Claude(show_reasoning=True)`, `GPT(show_reasoning=True)`, `"reasoning"` in a `call_with_tools` result, and a
201
+ `{"type": "reasoning"}` runner event.
202
+ - **MCP sign-in from a remote window.** The sign-in page is a card in the window, and pasting the address of the
203
+ page that could not load afterwards finishes the sign-in on the agentx computer.
204
+ - **Conversation titles and closing the window.** After its first answer, a conversation gets a short title from the
205
+ model (one small request, on a thread of its own), shown in the app window's list and in `/resume`; older ones
206
+ show the first thing you typed, no longer agentx's summary note. Closing the app window quits agentx (a running turn
207
+ stops and is kept, the conversation is saved); a reload does not. Not with `--no-open` or `--remote`.
208
+ - **`agentx`: commands while it works, and `/unsend`.** Commands that only show something (`/usage`, `/settings`,
209
+ `/help`, `/team log`, `/skills`, `/mcp`, `/memory`, `/sessions`, and `/model`, `/team-models`, `/limit`,
210
+ `/fullscreen` with nothing after them) run at once while the agent works, and `/mode` changes the mode at once;
211
+ they used to wait (`runs when the agent is done`). `/voice` starts recording at once: Enter stops it and the words
212
+ go into the line being typed, to check and send. `/unsend` takes back a waiting message (or a team note) before it
213
+ is read: the newest, `/unsend 2`, or `/unsend all`; the waiting lines are numbered. Commands that change the
214
+ conversation or the setup still wait. The agent and the team's runner are told not to wait inside a command
215
+ (`sleep`, `--watch`): they check CI or a deploy once and report. The zero-to-hero guide has `/init` as step 4.
216
+ - **`agentx`: `/voice`.** Records from the default microphone until Enter (Ctrl+C cancels), writes out what was said
217
+ with OpenAI's speech-to-text (`gpt-4o-transcribe`, falling back to `whisper-1`; `AGENTX_VOICE_MODEL` picks another)
218
+ and puts the words in the next input line to check before sending, in the normal and the full-screen screen.
219
+ Claude models take no audio, so it needs `OPENAI_API_KEY` whatever the chat model. The microphone is read with
220
+ `sounddevice`: new extra `agentx-dev[voice]`. A recording stops by itself at 10 minutes; a microphone that cannot
221
+ record at 16 kHz records at its own rate.
222
+ - **Agents can look at pictures.** `read_path` on a PNG, JPEG, GIF or WebP file hands the model the picture itself
223
+ (it used to answer `file is not utf-8 text`), so an agent or a team helper that takes a screenshot can see it. It
224
+ works on Claude (inside the `tool_result`) and GPT (Chat Completions and Responses: the tool message gets the text,
225
+ and a message right after the tool results carries the picture). The type comes from the file's contents; a
226
+ picture over 5 MB or 8,000 pixels is made smaller with Pillow when it is installed, and refused otherwise. Each
227
+ request carries the newest three pictures from tool results; older ones become a note naming the file (the history
228
+ keeps them). Logs, the screen and team summaries show one line (`Picture shot.png: PNG, 1440x900, 245 KB.`); in
229
+ `agentx` the tool line reads `Picture, 1440x900`. In `agentx` a picture outside the project folder (a screenshot in the user's Pictures folder) is opened after an approval prompt instead of being refused; other files outside stay refused. The agent and the team planner are told they can do this. New
230
+ module `agentx_dev.Pictures` (`picture_result`, `ToolContent`) for tools of your own.
231
+ - **`agentx`: type while the agent works.** On the normal screen what you type while the spinner runs shows under it,
232
+ and Enter sends it to the agent at its next step, so it can change course without waiting. During a team job a
233
+ message goes to the team: running helpers read it at their next step, later steps start with it, and the main
234
+ agent reads it in the job's result (to add work). `/skip <step number or helper>` skips a team step not started
235
+ yet. Another command typed then runs when the agent is done. A sent message waits under the spinner (`◌ ...`) and,
236
+ once read, leaves one line: `❯ text ✓ read by <the agent or the helper>`. The spinner says `type to add to the
237
+ task`. Full-screen mode does the same (a message typed
238
+ there used to wait for the end of the turn). Approval prompts still get every key.
239
+ - **`AgentRunner.interjections` and `AsyncAgentRunner.interjections`.** Set it to a function that returns the messages
240
+ a user sent while the run was going; each is added to the run before the next step, and `stream` yields
241
+ `{"type": "interjection", "content": ...}` for it.
242
+
243
+ - **`log=` on `AgentRunner` and `AsyncAgentRunner`: watch a run as it goes.** `log=True` prints one short line per
244
+ step to stderr; a file path appends JSON lines (`.jsonl`) or readable lines; a `logging.Logger` sends them to your
245
+ logging setup; a function receives each event. Lines: the start, each model call (time, tokens in, cached and
246
+ out), each tool result (ok or error, arguments and result cut short), and the end (outcome and totals) or the
247
+ error. Secrets are redacted, and a log that cannot be written never stops the run. New `RunLog` class
248
+ (`RunLog.chain` writes to several). See "Watching one runner" in the observability guide.
249
+ - **The eval harness catches up.** `EvalRunner` runs an `AsyncAgentRunner`, a `Supervisor` or an `AsyncSupervisor`
250
+ as well as an `AgentRunner` (async ones from a notebook too); new checks `outcome_is`, `output_field`,
251
+ `used_skill`, `used_agent`, `subtasks_ok` and `EvalCase(max_tool_errors=)`, with the same fields in JSON cases;
252
+ `repeat=` runs each case several times (the summary shows `[2/3]`), `tags=` picks cases; results carry
253
+ `counted_tokens` (cached input as a tenth), `model_calls` and the failed tools; `compare_reports` and
254
+ `python -m agentx_dev.Evals compare a.json b.json` put two reports side by side; the CLI takes `--repeat`,
255
+ `--tag` and `--log`.
256
+
257
+ - **Public extension points on `Supervisor` and `AsyncSupervisor`:** `prepare_plan(plan)` (change a plan before it
258
+ runs), `run_step(agent_name, query, run)` (wrap or skip every step), `spawn_specialist(spec)` (build the helpers a
259
+ plan defines your own way) and `planner_note` (text added to the planner's list of specialists). A planned helper's
260
+ `new_agent` may name a `model`, kept by the plan checker and passed as `AgentSpec.model`. The `agentx` team runner
261
+ now uses only these, no underscore methods. See "Changing how a Supervisor runs" in the sub-agents guide.
262
+
263
+ ### Changed
264
+
265
+ - **`Claude()` defaults to `claude-opus-5-5` with `max_tokens=16000`** (was `claude-sonnet-4-6`, 4096). Opus 5.5
266
+ always thinks and the thinking counts toward the limit, so 4096 could cut answers short. `agentx`'s help text and
267
+ hints name `claude-opus-5-5` and `gpt-6.1-sol`. See Upgrading.
268
+
269
+ - **`Supervisor` and `AsyncSupervisor` share one core.** Planning, replanning, synthesis, a step's retries and the
270
+ rounds of a session are written once (they were two copies that had to be fixed twice). `AsyncSupervisor` awaits
271
+ real work; `Supervisor` runs the same code with sync calls, still in your thread, with no event loop, so it keeps
272
+ working in a notebook. Each class keeps its own way of running a plan: one step at a time, or side by side. No
273
+ change in behaviour: the same events and log lines.
274
+
275
+ - **Smaller source files.** `Supervisor.py` (2,900 lines) keeps the two classes; its helpers moved to the private
276
+ package `agentx_dev/_supervisor/`. The `agentx` app's `ChatApp` gets its MCP, model, usage and team commands from
277
+ four files (`cli/app_mcp.py`, `app_models.py`, `app_usage.py`, `app_team.py`), and `cli/ui.py` its text and input
278
+ helpers from `ui_text.py` and `ui_input.py`. Every name is still importable from where it was.
279
+
280
+ - **The public API is written down** in `docs/reference/public-api.md`: every name exported from `agentx_dev`, the
281
+ stable import paths below it, what is not public (underscore names, the `agentx` command's Python modules), and
282
+ how patch, minor and major versions may change it. A test fails when the package and the page disagree.
283
+
284
+ - **A smaller base install.** `chromadb`, `qdrant-client`, `psycopg`, `pandas` and `openpyxl` moved from the base
285
+ dependencies to extras: `[rag]` (the three vector stores; `[chroma]`, `[qdrant]`, `[pgvector]` one at a time),
286
+ `[excel]` (spreadsheets in `Media`), `[all]`. A missing package's error names the extra. See Upgrading.
287
+
288
+ - **The package says what it is.** The PyPI summary, keywords, README opening, docs index and docs site name both
289
+ halves: the framework and the `agentx` terminal assistant, with helpers that run in parallel. New cookbook pattern
290
+ 40, "Let helpers work in parallel", for the terminal app and for `AsyncSupervisor` in your own code.
291
+
292
+ ### Fixed
293
+
294
+ - **The iPad's link keeps working after the computer sleeps.** Tailscale could stop sharing agentx's port (after a
295
+ sleep or a Tailscale restart) while agentx still ran, so the link was dead. agentx now checks every 30 seconds
296
+ and shares it again (the same link), saying so in the terminal, and at start clears entries earlier runs left
297
+ shared with nothing behind them. The tests no longer reach the Tailscale of the machine they run on.
298
+ - **The ssh command for another computer uses the Wi-Fi address again.** With Tailscale on, it used this computer's
299
+ Tailscale address (100.x), which times out from a laptop without Tailscale; the Tailscale address is now offered
300
+ as the one to use from a computer with Tailscale on.
301
+ - **The app window shows agentx at work, as the terminal does.** In `/remote-control` from the terminal it said
302
+ "Waiting for agentx…" with nothing moving: now the spinner line (what it does, the time and the tokens this
303
+ message has used) shows there too, starts the moment a message is sent, and a soft light runs along the message
304
+ box while it works. A conversation starts with the agentx header (version, model, folder), like the terminal's
305
+ box, and the link and ssh steps of `/remote-control` stay in the terminal instead of filling the window.
306
+ - **"Open in Safari" opens the app window, not a box saying to start agentx.** The page took its key out of
307
+ the address, so opening it in another browser, a new tab or from a bookmark had none, and the box could not be
308
+ closed. The key now stays in the address after a `#` (never sent to the server). Without a key, or with one from
309
+ an earlier start, the box says which, and takes the link agentx printed pasted in.
310
+ - **`agentx --remote` opens the terminal with remote control on.** Before, `--remote` needed `--ui` and gave the app
311
+ window only; now `agentx --remote` is `agentx` followed by `/remote-control` (`--ui --remote` still serves the
312
+ window only).
313
+ - **When Tailscale gives no link for the iPad, agentx says so first.** HTTPS or Serve turned off in the Tailscale
314
+ account (also after it worked) left only the 127.0.0.1 address, with the reason under the SSH steps; now the reason
315
+ and where to turn it on come first, Tailscale's own link to allow Serve is passed on, and agentx no longer waits
316
+ 20 seconds for Tailscale there.
317
+ - **The app window's Details panel fits the screen.** A long MCP server name or address stretched it, so on an iPad
318
+ it scrolled sideways; long names and addresses now wrap inside it. Below a wide desktop window (an iPad, a
319
+ half-screen window) it slides over the chat instead of squeezing it, and tapping beside it or Escape closes it.
320
+ - **`agentx`: a turn that stops before it finishes is kept.** Out of credit, any other error, Ctrl+C or the token
321
+ limit used to drop the whole turn, so after switching model (say Claude ran out of credit) the new model did not
322
+ know what the stopped turn had changed. Now your message and a short record (files changed, commands run, the last
323
+ thing it said, why it stopped) go into the conversation and the work log, and `continue` picks up from there, on
324
+ the same model or after `/model <name>`. An out-of-credit error says so plainly and what to do instead of
325
+ printing the raw `BadRequestError`. Leaving prints how to come back: `agentx --continue` (with `--model <name>`).
326
+ - **`run_shell` and `run_python` stop at their time limit.** On Windows the limit killed only the shell and then
327
+ waited, with no limit, for programs it had started (`ssh`, `sleep`, a dev server) to close the output, so a 5-minute
328
+ limit could run for as long as such a program did (`Running run_shell... 7m 28s`). The whole process tree is now
329
+ stopped at the limit, and the timeout message keeps what the command printed before it. A command that ends but
330
+ leaves a program running in the background without redirecting its output (`cmd &`) returns at once with a note
331
+ on how to start it (`nohup cmd > log.txt 2>&1 &`) instead of holding the tool until the limit. Commands get an
332
+ empty stdin, so none can read the terminal. Ctrl+C while a command runs now stops it and everything it started
333
+ (a hung `ssh` used to keep the turn waiting after "Turn interrupted").
334
+ - **A helper that calls a tool it does not have is told so and carries on.** A "final checks" step that also had to
335
+ fix what failed went to the runner (it runs commands but cannot edit); its call to `edit_file` ended the step with
336
+ "(agent emitted an unrecognized action and no answer text)", shown as Done. agentx's agent and helpers now get the
337
+ framework's `strict_tool_dispatch` reply (the tool is not theirs, here are the ones they have), a step that still
338
+ ends with no report is marked failed, and the planner is told to give a step only to a helper with every tool it
339
+ needs.
340
+ - **A team job uses the GPT models in `teamModels` too.** With a Claude chat model and `gpt-6-luna` in the list
341
+ (its key found), every step of every job ran on a Claude model: the planner was told "no model is preferred" and
342
+ picked its own provider. It is now told the user listed these models so the work is shared among them, and, when
343
+ the list has both Claude and GPT models, to give at least one step to each provider.
344
+ - **Team steps start in plan order.** When a step finished and freed two steps at once, the one that had been waiting
345
+ longer went first: step 3 ran before step 2. A step now gives way to an earlier step that is ready at the same
346
+ time (for at most 3 seconds, so a step that never starts cannot hold up the rest).
347
+ - **The spinner shows minutes**: `Team is working... 11m 23s`, not `683s` (and `1h 02m` past an hour).
348
+ - **`agentx --model claude-opus-5.5` works.** A Claude name written with a dot got a 404 ("model: claude-opus-5.5
349
+ was not found") on the first message; it is now read as the dashed id (`claude-opus-5-5`). GPT names keep their dot.
350
+ - **A `teamModels` note may be 200 characters** (was 80, and a longer one was dropped at every start). A note past
351
+ 200 is now shortened, with a warning, instead of dropped.
352
+ - **A step with no action and no answer no longer ends the run.** A reply cut off by the output limit (seen with a
353
+ Claude Sonnet 5.5 helper after 20 tool calls) came back empty and the run ended with "(agent emitted an
354
+ unrecognized action and no answer text)". The model is now asked again, up to twice per run.
355
+ - **`agentx` finds an API key saved in Windows after the terminal was opened.** A team model on the other provider
356
+ showed `Not used: gpt-... (no OPENAI_API_KEY)` when the key was set with `setx` or the Environment Variables dialog
357
+ after the terminal started. agentx now reads a missing `ANTHROPIC_API_KEY` or `OPENAI_API_KEY` from the saved user
358
+ (then system) variables at start, before each team job and on `/model`, and says which it used (never the value).
359
+ - **A team job's task may be 12,000 characters** (was 4,000): the main agent's detailed tasks were refused twice in
360
+ one job.
361
+ - **Claude: every agent request was declined on claude-opus-5 and claude-opus-5-5.** The agent's step tool asked
362
+ for a `Thought` (the model's reasoning, written out), and these models decline a request that asks for their
363
+ reasoning (`stop_reason: "refusal"`, category `reasoning_extraction`) before writing anything: `agentx` showed
364
+ nothing at all, or "unrecognized action". The step tool is now sent to Claude without its `Thought` field
365
+ (GPT keeps it). And a decline, or `max_tokens` used up with nothing written, now raises `ModelDeclined` with the
366
+ provider's reason (also in `agentx.log`) instead of returning an empty answer.
367
+ - **Evals: failed tool calls were never counted.** The count looked for results starting with "ToolError" in
368
+ `completion.tool_calls`, which lists only the calls that worked, so it was always 0. It now counts them from the
369
+ run log, recovered ones included.
370
+ - **`agentx`: an installed skill is ready at once.** `/skills install` and `/skills remove` used to wait for a new
371
+ conversation (`/clear`, or a restart); now the conversation you are in gets the change, with its history kept.
372
+ `/skills reload` does the same for a skill folder copied in by hand.
373
+ - **`agentx`: Claude models use prompt caching.** `agentx` built Claude models without it, so every step of a long
374
+ run sent the whole conversation again at full price and counted it in full against the token limit (one helper
375
+ used 229k tokens on 8 tool calls and stopped part-way). The system prompt, the tools and the conversation so far
376
+ are now read from Anthropic's cache on the next step, billed and counted at about a tenth.
377
+ - **`agentx`: a run that hits the step limit shows what it did.** It ended with nothing on the screen; it now shows
378
+ the summary and says to type `continue`. The limit is 300 steps a message (was 50): `"maxSteps"` in your settings
379
+ or `--max-steps` changes it. A short "continue" (or "go on", "carry on", "keep going") right after that stop
380
+ tells the agent to pick up from its last step instead of re-running the checks already in the conversation.
381
+ - **`agentx`: a team job saves every helper's work as it goes**, in `.agentx/team/<date>-<task>/` (`job.md` and one
382
+ file per step with the helper's whole report), and the finished reports join the project's `recall` index: a
383
+ closed terminal no longer loses the research.
384
+ - **`agentx`: team steps are shown by role.** The planner gives every step a name for what its helper does
385
+ (`git-checker`, `payments-fixer`, `migration-verifier`), shown in the plan, the live block, the done lines and
386
+ `/team log` in place of `runner` / `coder` (`git-checker@claude-sonnet-5-5`). The step still runs on the
387
+ built-in helper; a step without a name shows the helper's as before.
388
+ - **`agentx`: `/skills install` fetches only the skill files.** It asks GitHub for the repository's file list and
389
+ downloads just the skill folders' files, so a big repository costs what its skills weigh (`morluto/rea`, 6,677
390
+ files and 130 MB, was refused as "too many files"; its skill is 8 files). Skills in hidden folders such as
391
+ `.agents/skills` are found (they were skipped), a `/blob/.../SKILL.md` link installs that skill, and the archive
392
+ fallback counts only the files it unpacks.
393
+ - **`agentx`: `/skills install` handles repositories with big demo files.** Only the folders holding a `SKILL.md`
394
+ (or the folder the link names) are unpacked, so a repository's videos and docs no longer count: the download may
395
+ be up to 100 MB, and a skill's own files up to 10 MB each (music, fonts), 50 MB in all.
396
+ `latent-spaces/brag` (65 MB, mostly demo videos) was refused as "bigger than the limit". Names before the link
397
+ install only those skills (`/skills install brag <link>`), a misspelt subcommand gets "Did you mean /skills
398
+ install?", and an over-limit download says what the limit is.
399
+ - **Structured output on Opus 5.5, Sonnet 5.5 and Fable 5.1.** These models answer a forced tool choice with a
400
+ 400, which `output_schema` and the answer parser used. The call now goes with `tool_choice: auto` and a line
401
+ asking for the tool; another model that refuses it is found from the error and remembered.
402
+ - **`agentx`: a saved model whose key is gone no longer stops the start.** When the other provider's key is set
403
+ (you moved from GPT to Claude, say), `agentx` lists that provider's models (Claude: `claude-opus-5-5`,
404
+ `claude-sonnet-5-5`, `claude-haiku-5-5`, `claude-fable-5-1`) or asks for a name, uses the one picked, and offers
405
+ to save it in the settings file the old name came from.
406
+ - **An OpenAI model that needs the Responses API for tool calls is found out once per program, not once per model
407
+ object.** Each new `agentx` session, team helper and benchmark task used to send one chat-completions request that
408
+ the provider rejected before switching. Now the switch is remembered for that model at that address until the
409
+ program exits.
410
+ - **Benchmark:** a result file keeps the whole model name (`gpt-6.1-sol` was saved as `gpt-6.json`), and an answer
411
+ check says which words it found instead of "the answer covers it". The first baseline, 10/10 on `gpt-6.1-sol`,
412
+ is in `bench/results/`.
413
+ - **`agentx`: cached input counts as a tenth toward the token limit and each team step's share.** A helper's
414
+ requests are mostly input the provider serves from its cache, billed at about a tenth, but they were counted in
415
+ full: in one audit each explorer was cut off after about 15 calls at "220k tokens", reported partial, and the agent
416
+ started two more team jobs. The limit question also says how many tokens were sent in full, and the team block and
417
+ done lines show the cached share (`230k tokens, 80% cached`).
418
+ - **`agentx`: helpers can open `auditing-a-project`** (version 2; it was listed only for the main agent, so helpers
419
+ told to follow it searched the disk for it). A step's report line drops markdown marks (`##`, `**`).
420
+
421
+ - **`agentx`: a no at the token-limit question now ends a team job cleanly.** New steps still started after the no
422
+ (three explorers at once, in one audit), and skill reads were not refused, so wrapping up ran past its allowance and
423
+ the whole turn was thrown away. Now no step starts after a no (it is listed as `not started`), `use_skill` is refused
424
+ like every other tool, and the team reports with what it has.
425
+ - **`agentx`: files are read with the file tools.** The base prompt and the runner helper say to read files with
426
+ `read_path` and search with `grep`/`find_files`, not print them with `run_python` or `run_shell` (one audit's runner
427
+ spent its whole token share printing files with Python). Helpers open a skill only when their step names it or it
428
+ covers exactly that step.
429
+
430
+ - **`agentx` team helpers no longer read the same files over and over.** Helpers kept 12,000 to 24,000 characters of
431
+ tool results whole, lost the files they had read and read them again (eight to ten times each on one audit, about
432
+ 2.5 million tokens and twelve limit questions). They now keep 20,000 to 40,000 like the chat, and a third whole read
433
+ of a file that has not changed in the step gets a note instead (an edit or any command resets it; a read with
434
+ `offset`/`limit` always works).
435
+ - **A team's report reaches the chat whole.** The result text is cut at 20,000 characters (was 6,000, which cut an
436
+ audit's findings and made the agent start a second job).
437
+
438
+ - **The wheel installs only `agentx_dev`.** `examples` and `host` (the docs site) were installed as top-level
439
+ packages too; they stay in the source download. The license is now an SPDX expression (`MIT`, with
440
+ `license-files`), which needs setuptools 77 or later to build.
441
+ - **An MCP sign-in survives a restart.** The SDK loaded a saved token as never expiring, sent it after it had run
442
+ out, and asked for a new sign-in instead of renewing it; after a restart it also guessed the renewal address
443
+ (`<server>/token`, a 404 for Supabase). agentx now keeps when the token runs out and the server's OAuth details from
444
+ the sign-in, and hands both back, so the token is renewed at the right address.
445
+ - **MCP sign-in to servers that issue a client secret (Supabase).** A secret given without a method is now sent
446
+ in the token request; the sign-in failed with "Required parameter: client_secret".
447
+ - **One stuck request no longer waits about 12 minutes.** A timed-out request is retried once at most (the client
448
+ has usually retried it already; a timed-out request may still be billed), and a 429 waits for its `Retry-After`.
449
+ - **A spent budget is not retried.** `CostBudgetExceeded` (and anything `model.on_usage` raises) is raised once; on
450
+ the plain chat path the call used to be retried up to three times after the budget was spent, paying each time.
451
+
452
+ ### Added
453
+
454
+ - **A benchmark for `agentx`** (`python -m bench`): ten fixed tasks on two sample repos (find, explain, fix, fix and
455
+ test, validate, add a feature, rename, audit, a team job, run and report), each checked automatically (the tests,
456
+ hidden tests, the files), with pass/fail, time, model requests, tokens, the cached share and tool calls recorded;
457
+ `compare` sets two runs side by side. It asks before it uses your API key. See `bench/README.md`.
458
+ - **`agentx`: `/mcp reload [name]`** (also `/mcp refresh`): reads `~/.agentx/mcp.json` again and reconnects every
459
+ server (or one) with the saved sign-ins, never opening the browser; servers taken out of the file are dropped and
460
+ the conversation gets the new tools. On Windows it also reads the user's saved environment variables, so a key set
461
+ with `setx` after the start is found. `MCPManager.reload(name=None, env=None)`.
462
+ - **`agentx`: full-screen mode** (`agentx --fullscreen`, `/fullscreen on|off`, `"fullscreen": true` in
463
+ `~/.agentx/settings.json`; off by default). The welcome box, the input and the status line stay put while only the
464
+ conversation scrolls (mouse wheel, PgUp / PgDn, Ctrl+End). Questions are asked above the input; a message typed
465
+ while the agent works is kept for later; Ctrl+C and Ctrl+D work as before; on exit the conversation is written to
466
+ the terminal. The app runs unchanged on a worker thread: its console writes into the screen, and the spinner is
467
+ drawn by the screen (`Progress.drawn_by`).
468
+ - **`agentx`: the agent looking around is one tree.** Skill reads, `recall`, reads, searches, listings and web calls
469
+ in a row are drawn as one flow (`● Skills using-superpowers` / `├─ recall ...` / `│ ⎿ Found 2 notes` /
470
+ `└─ read_path ...`), redrawn in place above the spinner while it runs (a blinking yellow dot, the running step
471
+ blinking white) and printed when the agent moves on, with a green dot (red when the last step failed). The agent's narration leading into those steps or into its answer is no longer printed; a note before
472
+ an edit or a command still is.
473
+
474
+ - **`agentx`: the supervisor can make helpers.** A plan step may define a helper (`new_agent`: a name, instructions,
475
+ tools). agentx builds it the way it builds explorer, coder and runner (gated tools, step
476
+ wrapping, redaction, 100 steps, trimming, skills); its tools come only from the gated set, never `delete_path`,
477
+ `move_file`, `start_team_job` or `delegate`, and it gets only the MCP tools it names. A helper with only reading
478
+ tools runs beside other reading steps. At most 6 per job; the plan shows each one and its tools. With helper
479
+ models set (`/team-models`), it may run on one of them (`"model"` in `new_agent`, read before the plan checker drops
480
+ it): the planner is told the list, a model not on it is not used, and the name shows it (`reviewer@gpt-6-luna`).
481
+ - **`Skills(guard=fn)`**: `fn()` is asked before each `use_skill` read; a text it returns is the answer instead.
482
+ - **`agentx`: reading steps of a team job run side by side.** Explorer steps that do not depend on each other run
483
+ up to 3 at once (`AsyncSupervisor` with `max_parallel=3` and a lock: a coder or runner step runs alone). A plan
484
+ without `depends_on` keeps its order, with neighbouring explorer steps grouped. Helpers run in worker threads; every
485
+ approval, team question, limit question and screen line is handed to the main thread, so prompts never overlap,
486
+ and Ctrl+C stops the job at once (a helper stops at its next tool call or model reply).
487
+ - **`agentx`: each team step has a token share,** one token limit's worth (at least 100,000); past it the step's
488
+ tools tell the helper to report what it has.
489
+ - **`agentx`: `a` at the token-limit question** goes on and does not ask again in this message.
490
+ - **`agentx`: team helpers work in the background.** Their tool calls are no longer printed. A block above the
491
+ spinner, redrawn in place, shows one line per running step (helper · step name, what it has done, time, tokens);
492
+ a finished step leaves one line (`✓ explorer · security audit Done (20 tool uses · 41k tokens · 1m 30s)`) and the
493
+ start of its report. `/team log` lists every call of the last team job. Steps are named by their plan id.
494
+ - **The `auditing-a-project` skill** (bundled): map, run the project's own checks, read by area with explorers side
495
+ by side, verify, and report Fix first / Medium / Low / Done well / Checks / Test gaps. `delegating-work` (version
496
+ 2) says which steps run side by side.
497
+
498
+ - **Smaller requests.** `AgentRunner(..., trim_results=True)` (and `AsyncAgentRunner`, or a `TrimPolicy` from
499
+ `agentx_dev.Runner.Trim`) sends the model a one-line stub in place of each big tool result outside a window of the newest
500
+ ones (20,000 to 40,000 characters, moved in steps, at least the newest one), stubs an older word-for-word copy of a later result, and shortens long
501
+ arguments of old calls; the saved history is unchanged and `use_skill` results are never
502
+ trimmed. `Permissions.read_max_chars` makes `read_path` return a long file in numbered parts with a note on how
503
+ to continue. `Skills(remember_reads=True)` answers a second read of a skill with a pointer back.
504
+ - **`agentx`:** all of the above are on (reads in parts of 30,000 characters); summarising starts at 60,000
505
+ characters (was 150,000) and is measured on what the model is sent. On a measured 15-file turn the input sent
506
+ fell from about 231,000 tokens to about 136,000. `/usage` shows the tokens used this session, per model, and by
507
+ the last turn.
508
+ - **Fewer whole-file re-reads.** A trimmed `read_path` result now names the file and its line count (or the line
509
+ range of a slice) and says to grep it or read only the lines needed; `agentx`'s base prompt and the
510
+ `exploring-a-project` skill (version 3) tell agents to write down the facts they will need as they read.
511
+ - **Cache-friendly trimming.** `TrimPolicy(step_chars=)`: once the whole results pass `keep_chars`, the oldest are
512
+ stubbed in one go down to `keep_chars - step_chars` (default half), so the start of the request stays the same,
513
+ and cacheable, until the next step; `keep_last` is now 1. Team helpers keep 12,000-24,000 characters. On a replayed
514
+ 40-step team brainstorm the input cost fell by about 28-41%, depending on the cached price.
515
+ - **A short `AGENTX.md`.** This repo's `AGENTX.md` is now about 1,800 characters (was 13,300), since `agentx` sends
516
+ it with every request; the full guide moved to `docs/reference/agent-guide.md`.
517
+ - **Older skill texts are stubbed in a long conversation.** `TrimPolicy(shrink_exempt_at=60_000)`: past that many
518
+ characters of conversation, every `use_skill` result but the newest is sent as a note that the skill still applies
519
+ and how to reopen it. In `agentx`, `run_python` and `run_shell` output is cut at 30,000 characters (was 100,000 and
520
+ 40,000), with a note to print less. Replaying a 21-step message that read five skills, the input sent fell by
521
+ about 15%.
522
+ - **OpenAI cached tokens are counted** (`TokenUsage.total_cache_read_tokens`, from either API), and `/usage` shows how
523
+ much of the input came from the provider's cache.
524
+ - **A token limit per message in `agentx`.** Past 200,000 tokens (`/limit`, `"tokenLimit"` in settings; a project
525
+ may only lower it) agentx asks before it goes on; a no wraps up (tool calls are refused, the agent answers with
526
+ what it has, the turn is kept), and only a wrap-up that runs long too ends the turn like Ctrl+C.
527
+ `BaseChatModel.on_usage`, a hook called after every recorded reply, is what it uses.
528
+ - **Web tools in `agentx`.** `web_search` and `web_fetch` (readable text, at most 30,000 characters, marked as data
529
+ from the internet); the gate asks before each in `default` and `plan` mode (`a`: the rest of the session). The
530
+ `web-research` skill is listed, and the team's explorer gets them.
531
+ - **MCP servers in `agentx`.** `/mcp add <name> <url>` (`--sse`), `/mcp add <name> -- <command> [args]`, `/mcp remove`,
532
+ `/mcp login`, `/mcp logout`; kept in `~/.agentx/mcp.json`, `${VAR}` for keys. A browser sign-in (OAuth) runs only on
533
+ `/mcp login`; tokens go to the system's credential store (`keyring`, split across entries when long) and renew
534
+ by themselves. Tools appear as `<server>__<tool>` for the chat and every team helper, ask before running even in
535
+ auto mode, and their results are marked as outside data and cut at 30,000 characters. The `mcp` extra now needs
536
+ `mcp>=1.10,<2` (2.x changed the client API and is not supported yet) and `keyring>=24`.
537
+ - **MCP tools sorted by what they do.** The first time agentx sees a server's tools, the ones the server marks
538
+ read-only run without asking (saved per server in `mcp.json` as `allow`/`seen`); the rest ask. `/mcp tools <name>`
539
+ lists them, `/mcp allow|ask <name> <tool...|read-only|all>` changes them; allowing a destructive tool asks first.
540
+ - **Model requests in `agentx` wait up to 5 minutes and are retried visibly.** `model.on_retry(attempt, error,
541
+ delay)` is called before each retry; `agentx` prints a line.
542
+ - **Tool results are one line in `agentx`.** Under each call: `⎿ Read 51 lines`, `⎿ Found 2 files`, `⎿ 3 matches in
543
+ 12 files searched`, `⎿ Found 1 note`, a command's first line of output and how many more, or its exit code and
544
+ last line in red when it failed. Refusals and errors are still shown in full.
545
+ - **Skill reads are one line in `agentx`.** Their text is never printed; a run of them shows on the spinner as it
546
+ grows and then stays as `● Skills a → b → c (+ file)`, with the notes written meanwhile after it. A failed read
547
+ is still shown.
548
+ - **A new `agentx` start screen.** A box with the agentx mark, the model and folder, tips for this folder and
549
+ what's new; MCP sign-in problems as one warning line; notes with a bar down the left; a rule above the input
550
+ and the mode under it (`⏵⏵ auto mode on (shift+tab to cycle) · model · folder`).
551
+ - **`agentx` input colours:** the `/name` at the start of the input line is coloured as you type (command cyan, skill
552
+ magenta, unknown red) and the selected row of the `/` pop-up is highlighted.
553
+ - **Skills first.** The skill list tells the model to check it before choosing tools and to prefer a skill the user
554
+ installed when it fits; the user's own skills are listed ahead of the built-in ones, and the terminal app's base
555
+ prompt says the same.
556
+ - **`agentx` project notes and recall:** a readable note per worthwhile turn in `.agentx/notes/` (asked, result,
557
+ files changed, commands), indexed in `.agentx/memory/` with OpenAI embeddings when `OPENAI_API_KEY` is set
558
+ (local similarity search otherwise, keywords if both fail). The agent gets a `recall` tool, a fresh
559
+ conversation's first message gets up to 3 close notes, and `/memory [words]` shows or searches them.
560
+
561
+ - **Skills.** `AgentRunner(..., skills=True)` (and `AsyncAgentRunner`) gives an agent a `use_skill` tool and a short
562
+ list of skills at the end of its system prompt; the model reads a skill's full text only when it needs it. The
563
+ list is built the same way every time, so the prompt stays identical for the provider's prompt cache. Five
564
+ skills ship with agentx (`exploring-a-project`, `changing-files`, `running-code`, `web-research`,
565
+ `delegating-work`) and are created in `~/.agentx/skills/` on first use; edits and deletions are respected. The
566
+ agent's own tools are described by a generated `custom-tools` skill. `SKILL.md` folders written for Claude work
567
+ as they are. See the new [guide](docs/guides/skills.md).
568
+ - **`agentx` terminal app:** skills are on by default; `/skills` lists them, `/skills install <github link or
569
+ folder>` installs after showing what it found (the exact commit is downloaded and recorded; archives are
570
+ unpacked with path, link and size limits), `/skills remove <name>` deletes one. Every skill the agent has is also a slash command: typing `/` lists the commands and then the skills, and `/<skill> [what you want]` (or `/skills use <name> ...` for a skill named like a command) makes the agent read that skill and do the task. Team helpers get `use_skill` and the skills that fit their role's tools, so a team step can use a skill; a helper's skill reads show on screen like its other tool calls (`● [explorer] use_skill brainstorming`); `/skill` is a short form of `/skills`. Only the user can install: the
571
+ agent has no tool for it, and `.agentx/*` and `~/.agentx` stay protected from its file tools.
572
+
573
+ ## [3.7.0] - 2026-10-15
574
+
575
+ ### Added
576
+
577
+ - **The `agentx` command**: a terminal coding assistant (`agentx`, or `python -m agentx_dev`), built on
578
+ `AgentRunner`, `DefaultTools` and `Session`. Run it in a project folder; it works with GPT and Claude from
579
+ `OPENAI_API_KEY` / `ANTHROPIC_API_KEY`. Flags: `--model`, `--mode`, `--add-dir`, `--continue`,
580
+ `--resume [ID]`, `--version`. See the new [guide](docs/guides/cli.md).
581
+ - **Approvals and modes.** Reads run; edits, commands and delete / move ask first, with a diff or the full
582
+ command shown. Modes `default`, `accept-edits`, `plan` and `auto` (edits, shell and Python run without asking; delete, move and unknown tools still ask; entered only on purpose, never from Shift+Tab, an `a` answer or a project settings file). Answering `a` ("don't ask again") remembers
583
+ all edits or a plain command prefix for the conversation, never for interpreters, shells, compound
584
+ commands, `run_python`, delete or move. A preview that cannot be shown, or a command over 20,000
585
+ characters, is declined with the reason.
586
+ - **Default protections.** Writes, edits, deletes and moves of the whole `.git`, of `.agentx/*` in the
587
+ project, and (when the home folder is reachable) of `~/.agentx`, git config files and common shell
588
+ profiles are always refused, in every mode. Deny and allow rules are a convenience layer, not a secrets
589
+ vault: `grep`, `find_files` and `list_directory` can still read a file a read rule denies, and
590
+ `run_shell` / `run_python` are not covered by path rules.
591
+ - **Settings and rules.** `~/.agentx/settings.json` and `.agentx/settings.json` (`model`, `mode`,
592
+ `addDirs`, `permissions.allow` / `deny` as `tool:glob`). Project settings are untrusted: an
593
+ `accept-edits` mode and `addDirs` outside the project are ignored with a warning, and the project's
594
+ allow rules are listed at startup and honoured only if you answer yes to "Honour these project rules?"
595
+ (deny rules from the project are always kept).
596
+ - **`AGENTX.md` context.** `~/.agentx/AGENTX.md` and the files from the working folder up through its
597
+ parents are passed to the model as instructions (nearest last, 20,000 characters); `/init` drafts one.
598
+ - **Sessions.** Conversations autosave to `~/.agentx/sessions/` and resume with `--continue`,
599
+ `--resume` and `/resume`. The files hold tool results (file contents) and are not encrypted.
600
+ - **Team jobs.** For a big job the chat agent can call `start_team_job` (the user approves each hand-off,
601
+ unless you run in auto mode or have allowed it with your own rule; `/team <task>` does it by hand): a
602
+ `Supervisor` plans up to six steps and three helpers (explorer reads,
603
+ coder edits, runner runs commands) carry them out one at a time. Every helper call goes through the same
604
+ gate, modes, deny rules and prompts as the chat; the result joins the conversation. A deny rule
605
+ `start_team_job:*` turns it off.
606
+ - **Helper models for team jobs.** Allow extra models with `teamModels` (in either settings file; a folder's
607
+ list replaces yours) or `/team-models`, and the supervisor picks per step which model a helper runs on
608
+ (Claude and GPT can be mixed when both keys are set). Every helper then names its model, the chat's own
609
+ included (`coder@claude-opus-5-5`, `runner@claude-sonnet-5-5`), with the same wording for every model so
610
+ none is favoured, and each model can carry a note on what it is for (`gpt-6.1-sol="hard coding"`), which
611
+ the supervisor reads; without one, the chat model is asked once what each model is good for and its
612
+ answer is kept as an `auto:` note (`/team-models describe` asks again). The approval box lists the models. A list that comes from a project's settings file
613
+ is announced at startup. With no list nothing changes. Team helpers now get 100 steps (was 25); a helper
614
+ that runs out of steps hands on its partial work instead of failing the step, and one message may run up to
615
+ 5 team jobs, so a big task continues batch after batch without you typing "continue". See the guide.
616
+ - **Project memory.** Each folder can have its own model: the first time you trust a folder, `agentx`
617
+ writes `.agentx/settings.json` with the model in use, and `/model <name> --folder` changes it (plain
618
+ `/model <name>` stays for the session). The app keeps a work log in `.agentx/log.md`, written by the app
619
+ (not the model) after each finished turn with the request, the files changed, the commands run and the
620
+ start of the answer; keys are hidden and the file is readable by its owner only where the platform
621
+ allows. A fresh conversation (a start without `--continue` / `--resume`, and `/clear`) starts from the
622
+ newest entries of that log, and a very long conversation is summarised before it overflows (the older
623
+ messages become one summary; the last six of your messages stay as they were). Not kept for the home
624
+ folder or a drive root. See the guide.
625
+ - **Slash commands.** `/help`, `/clear`, `/model`, `/mode`, `/settings`, `/resume`, `/sessions`, `/init`,
626
+ `/team`, `/team-models`, `/exit`. Typing `/` pops up the list with a one-line description of each. The
627
+ first run writes `~/.agentx/settings.json` with the model in use, once it is built, so there is a file to
628
+ edit; `/settings` shows what is in force and where the files are. A `"model": "(no model)"` line that an
629
+ earlier build of this release could write there is ignored with a warning to delete it.
630
+ - **Trust and menus.** The first start in a folder asks whether you trust it ("Accessing workspace", Yes /
631
+ No); nothing from the folder (`AGENTX.md`, project settings) is read before you answer, and the answer is
632
+ kept in `~/.agentx/trusted.json`. Choices are numbered menus you move through with the arrow keys and
633
+ confirm with Enter (or a number, or `y` / `a` / `n`): the approval prompt, the folder question and the
634
+ `/resume` list. Without a terminal they fall back to typed answers.
635
+ - **A prompt that looks alive.** The input prompt is coloured and its cursor blinks while it waits for you.
636
+ - **Progress.** While the agent works, a spinner with the seconds elapsed shows what it is doing
637
+ ("Thinking...", "Running run_python... 12s"). It is paused while a prompt waits and drawn only on a
638
+ terminal. Python code may run for 2 minutes and shell commands for 5 (the framework's defaults, 10 s and
639
+ 30 s, stopped web fetches and test runs); time spent waiting for approval does not count.
640
+ - **`Session.stream(user_input, **kw)`**: like `Session.invoke`, but yields the runner's events and absorbs the
641
+ result on the final `completion` event. A turn abandoned before then is not recorded.
642
+ - **New base dependency: `prompt_toolkit>=3.0`** (the input line: history, multi-line, completion, status
643
+ bar). `rich` was already a dependency.
644
+
645
+ ### Fixed
646
+
647
+ - **A conversation can continue after a run that ended on a final answer given as a function call.** With
648
+ function calling the model delivers its answer as a call (`React_` or `respond`) and the run ended
649
+ without a result for it, so the next turn was rejected by OpenAI ("An assistant message with
650
+ 'tool_calls' must be followed by tool messages" / "No tool output found for function call"). The history
651
+ a run returns now closes that call, and a history saved by an older version is repaired when resumed.
652
+ This affects `Session` and `chat_history` users as well as the CLI.
653
+ - **`edit_file` no longer rewrites a file's line endings.** It read and wrote through the platform's newline
654
+ translation, so on Windows an LF file came back CRLF and on Linux and macOS a CRLF file came back LF, with
655
+ every line changed. It now keeps every byte outside the edit. A model's bare newlines in `find` and
656
+ `replace` are put in the file's own ending (CRLF if the file mostly uses it), so CRLF files can be edited
657
+ across lines.
658
+
659
+ ## [3.6.2] - 2026-10-09
660
+
661
+ ### Added
662
+
663
+ - **`Supervisor(ask_when_done=True)` / `follow_up=True`** (and the same on `AsyncSupervisor`): when a
664
+ round's answer is ready the framework itself asks the operator "What should I do next?" through the
665
+ `ask_user` asker (the answer, the outcome and the question in one prompt) and returns the reply in
666
+ `SupervisorResult.next_step`. `follow_up=True` runs another round on each reply, with the earlier
667
+ results as context, until the operator replies blank or with a closing word (any of `done`, `stop`,
668
+ `quit`, `exit`, `no`, `nothing`, `that's all`, `that's it`, `all done`, `nope`, `bye`, `goodbye`,
669
+ `thanks`, `thank you`, `no thanks`, `no thank you`, `done thanks`, `done thank you`, `nothing thanks`,
670
+ `stop thanks`; case-insensitive; apostrophes (`thats all` works), commas, extra spaces and trailing `.`, `!`, `?` ignored); `max_follow_ups` (default
671
+ 5) bounds it and `SupervisorResult.rounds` lists the rounds. Asked whatever the outcome. The
672
+ checkpoint uses no `max_questions` slot and is never saved to memory; only round 1's result is.
673
+ New `checkpoint` and `round` stream events. Either setting needs `ask_user`. With `ask_when_done`
674
+ on, the Supervisor asks itself, so the planner and the helpers are told not to ask "what next?"
675
+ (no double question); the built-in terminal prompt puts the question first.
676
+
677
+ ### Fixed
678
+
679
+ - **"When done, ask me" now reaches `ask_user`.** With `ask_user=True` and a task that said to ask the
680
+ operator what to do when finished, the helper wrote the question into its answer and the run ended
681
+ with nobody to answer. A helper's instruction covered only a missing fact; it now also covers a task
682
+ that tells it to check with the user, and says to call `ask_user` at that point and act on the reply.
683
+ The planner is told to put that instruction in the step's query rather than plan a step that only
684
+ asks.
685
+
686
+ - A planner-defined helper built with no tools (a research step the planner forgot to give `web`) is
687
+ now called out in the verbose `[spawn]` line ("no tools, so it can only reason"). The planner is
688
+ reminded, as the last rule of the helper instructions, to give every `new_agent` the tools its job
689
+ needs, and `capabilities` is accepted as an alias for `tools` in a `new_agent` (the 3.5 spelling).
690
+ - The verbose line "has the same tools as the registered specialist" no longer fires because both
691
+ agents were given `ask_user`.
692
+
693
+ ### Changed
694
+
695
+ - **The vector-store clients are core dependencies.** `chromadb`, `qdrant-client` and `psycopg[binary]`
696
+ now install with `pip install agentx-dev`, so `ChromaVectorStore`, `QdrantVectorStore` and
697
+ `PgVectorStore` work without an extra. `[chroma]`, `[qdrant]` and `[pgvector]` remain as aliases.
698
+ The base install is larger (chromadb brings onnxruntime and others); `anthropic`, `mcp` and
699
+ `opentelemetry` are still extras.
700
+ - The planner's catalog lists each registered agent's tools under its description (framework tools
701
+ `ask_user` and `delegate` left out, long lists cut at 12), so a description no longer has to say
702
+ that an agent can write files. Registered agents whose runner has no tool registry are unchanged.
703
+ - The verbose `[spawn]` line ends with `+ ask_user` for a helper that can ask. `result.spawned` is
704
+ unchanged.
705
+
706
+ ### Docs
707
+
708
+ - Sub-agents guide: how to let helpers write files (`capabilities={"web", "files"}` and
709
+ `allowed_paths`), the capability words, and asking at a checkpoint; FAQ entry.
710
+
711
+ ## [3.6.1] - 2026-10-09
712
+
713
+ ### Fixed
714
+
715
+ - A package that was installed but failed to import was reported as not installed. A user whose project
716
+ folder held a `google.py` saw "ChromaVectorStore requires the chromadb package" although chromadb was
717
+ installed: the file hid the real `google` package that chromadb's dependencies use, and the catch-all
718
+ hid that. The error now says which case it is. Not installed: it names the extra
719
+ (`python -m pip install "agentx-dev[chroma]"`) and the Python that is running. Installed but failing:
720
+ it shows the real error and common causes (a file named like a library, a version conflict) and no
721
+ install command. Applies to `ChromaVectorStore`, `QdrantVectorStore`, `PgVectorStore`, `MCPClient`,
722
+ `OTelHook` and `Claude`.
723
+
724
+ ### Docs
725
+
726
+ - Install pages list the `chroma`, `qdrant` and `pgvector` extras and say why a plain install leaves
727
+ them out; the troubleshooting page covers both messages.
728
+
729
+ ## [3.6.0] - 2026-10-09
730
+
731
+ Sub-agents: the Supervisor can create its own helpers. Opt-in, with the behavior changes listed below.
732
+
733
+ ### Added
734
+
735
+ - **Inline helpers**: a plan step can carry `new_agent` (name, free-form
736
+ instructions, tools). The helper runs the step, is reused by name, and is
737
+ discarded when the run ends. Recovery plans can define a replacement for a
738
+ stuck step.
739
+ - **`delegate` tool**: specialists hand a side job to a fresh sub-agent (clean
740
+ context) and get a short summary back; refusals are plain text and a helper
741
+ that fails comes back as a tool error the caller's stuck logic sees.
742
+ `AgentRunner(..., delegation=SpawnConfig(...))` gives a standalone runner the
743
+ same tool; `runner.spawned` lists what it created.
744
+ - **One ceiling**: `SpawnConfig(capabilities=..., tools=..., max_spawns=...,
745
+ max_depth=...)` bounds every helper; spawns inside it need no approval and
746
+ over-asks are clipped, not fatal. New read-only `files_read` preset.
747
+ - **`AsyncSupervisor(spawn_config=...)`**: async parity; spawned steps run in
748
+ parallel. `AsyncAgentRunner` gained `system_addendum=`.
749
+ - `SupervisorResult.spawned`, `spawn` and `delegate_result` stream events,
750
+ `AgentSpec`, `ToolRegistry.unregister`, `AgentRunner.add_tool` /
751
+ `remove_tool`.
752
+ - New guide: Sub-agents.
753
+ - **Ask the operator**: `Supervisor(ask_user=True | function)` lets the planner ask for facts the task
754
+ leaves out and gives every agent an `ask_user` tool. `True` uses a built-in asker that works in
755
+ notebooks (the input box), terminals and IDE consoles and never blocks a headless process; a
756
+ function routes questions through your own channel (chatbot, backend). `max_questions`,
757
+ `ask_timeout`, `SupervisorResult.asked`, `question`/`answer` events,
758
+ `agentx_dev.ask_human_tool()`; waiting on the operator pauses the persistent deadline. The built-in prompt names who is asking (`[planner]` or the agent's name) with a raised-hand marker. Each agent
759
+ may ask once per run (the planner may ask several questions in its one round), and after the
760
+ operator answers the planner is told to do the work instead of planning another question. The
761
+ helper-creation instructions now say a helper can only look things up with the tools it is given
762
+ (this applies to every Supervisor that enables spawning).
763
+ - **Supervisor long-term memory**: `Supervisor(memory=store)` (any vector store: `VectorStore`, Chroma,
764
+ Qdrant, pgvector) gives the planner and every dispatched step the few relevant stored items as a
765
+ FROM MEMORY block, saves each operator answer and each completed run's final answer, and answers an
766
+ exact repeat of an answered question from memory (a run whose synthesis was cut off by the budget
767
+ saves nothing). `memory_top_k`, `memory_min_score`,
768
+ `memory_write`, `SupervisorResult.memory`, `memory` stream events.
769
+ - `web_fetch_tool(text_only=True)`: return an HTML page as readable text (scripts, styles and tags
770
+ removed) instead of the first 50,000 characters of raw markup, which on a modern page can hold no
771
+ content at all. Default off (unchanged for existing agents); the helpers a Supervisor builds use it.
772
+ Helpers are also told not to answer with a script unless they have a code tool, and to say what
773
+ they tried and what was missing.
774
+ - `SpawnConfig(max_iterations=15)`: the step limit for the helpers a Supervisor creates (it was fixed at 15).
775
+ Registered specialists keep the limit set on their own `AgentRunner`. Helpers are told their step limit
776
+ so they can finish with a Final_Answer in time.
777
+ - A helper that runs out of steps (`iteration_limit`) is retried with a note that it ran out, a short
778
+ recap of what it did, and an instruction to do fewer lookups; other failures keep the generic retry note.
779
+ - The unknown-tool error now lists the valid tools and says that a response-format name such as `React_`
780
+ is not a tool, so a model that called one can recover.
781
+ - `RunBudget` now carries a `PausableClock` (it holds a lock), so a `RunBudget` can no longer be
782
+ deep-copied or pickled.
783
+
784
+ ### Changed
785
+
786
+ - A spawned agent no longer stays on the supervisor after the run.
787
+ - A spawn is no longer refused (or rerouted) because an existing specialist
788
+ has the same tools. The `spawn` event gained `origin`, `tools`, `dropped`,
789
+ `reused` and `refused`; `rerouted_from` is always `None`.
790
+ - A `Supervisor` / `AsyncSupervisor` with `persistence=` and no `spawn_config`
791
+ now allows helpers with web and read-only file access (`max_spawns=6`) and
792
+ gives its specialists the `delegate` tool. Pass
793
+ `spawn_config=SpawnConfig(enabled=False)` to opt out.
794
+ - A legacy spawn config (`enabled=True` with neither `capabilities` nor
795
+ `tools`) keeps the 3.5 approval flow and gives specialists no `delegate`
796
+ tool; set a ceiling to turn delegation on.
797
+ - The planner prompt teaches `new_agent` instead of the `__spawn__` step; old
798
+ `__spawn__` steps still work, but their `name` must now match
799
+ `[A-Za-z0-9_-]{1,40}`.
800
+ - Agent names starting with `__` and names of the form `delegate_<N>` are
801
+ reserved: a `new_agent` that uses one is dropped by plan sanitization.
802
+ - `SpawnConfig.max_spawns` is `Optional[int]` (unset: 3, or 6 in ceiling mode).
803
+ `SUPERVISOR_SPAWN_INSTRUCTION` was removed.
804
+
805
+ ## [3.5.0] - 2026-10-04
806
+
807
+ Agents that keep working through errors. Opt-in; one default change (below).
808
+
809
+ ### Added
810
+
811
+ - **Persistent mode** (`persistence=Persistence(...)`) for `AgentRunner`,
812
+ `AsyncAgentRunner`, `Supervisor` and `AsyncSupervisor`. When a run gets
813
+ stuck (the same call repeated, or tool errors in a row) it is
814
+ asked, in four escalating steps, to find the root cause, try a
815
+ different approach, probe its assumptions, and say what blocks it,
816
+ before it may stop; real progress resets the ladder. Runs stop on
817
+ `max_minutes` or the model's cost cap, not a step count.
818
+ - **Context compaction** for long runs: old turns become notes, the task
819
+ (with its attachments) and recent turns are untouched, and the failed
820
+ attempts are kept word for word.
821
+ - **Patient retries**: transient provider errors (429, 5xx, timeouts,
822
+ connection errors) are retried with backoff until the deadline; auth
823
+ and invalid-request errors still raise at once.
824
+ - **Supervisors replan**: a step that does not finish is replanned
825
+ around under one shared deadline; finished steps are kept and can be
826
+ depended on. A recovery step names the steps it redoes
827
+ (`"replaces": [...]`); a failed step counts as resolved only when its
828
+ replacement finishes. New `replan`, `reflect`, `compact` and `budget`
829
+ stream events.
830
+ - **Outcomes**: every completion has `.outcome` and (persistent runs)
831
+ `.progress`; `SubtaskResult` and `SupervisorResult` have `.outcome`.
832
+ - New guide: Long-running agents.
833
+
834
+ ### Changed
835
+
836
+ - A `Supervisor`/`AsyncSupervisor` now treats a specialist that finished
837
+ with an outcome other than `done` (for example `iteration_limit`) as a
838
+ failed attempt: it retries up to `max_subtask_retries` with the reason
839
+ fed back, then flags the step. Previously such a result was accepted
840
+ as a success. This applies without `persistence`. Consequences: each
841
+ give-up costs one extra attempt by default (`max_subtask_retries=1`);
842
+ the flagged step's recap is no longer passed to downstream
843
+ specialists; steps that `depends_on` it are skipped; and
844
+ `SupervisorResult.outcome` is `partial` or `stuck`.
845
+ - While `persistence` is set the tool-result cache is off, and the
846
+ iteration cap is `persistence.max_turns`.
847
+
848
+ ## [3.4.3] - 2026-09-26
849
+
850
+ Two path-resolution fixes for Windows sandboxes. Non-breaking.
851
+
852
+ ### Fixed
853
+
854
+ - **`full_access(["/workspace"])` now means the project's workspace
855
+ folder, not the drive root.** On Windows a rooted path without a drive
856
+ letter resolves to the current drive, so the sandbox became
857
+ `C:\workspace`; `auto_create_paths` then created it, and an agent
858
+ asked for `workspace/spam.csv` searched an empty directory outside the
859
+ project and reported the file missing. Slash-rooted sandbox roots are
860
+ now re-rooted at the running project, matching what a leading slash
861
+ already meant for tool arguments. POSIX absolute paths (`/workspace`
862
+ as a Docker mount) and drive-qualified paths are untouched.
863
+ - **`workspace/report.md` no longer nests into
864
+ `<workspace>/workspace/report.md`.** The `workspace` field documented
865
+ this pass-through, but only the `./workspace/...` spelling had it.
866
+ Models name the workspace folder constantly, so the missing case hit
867
+ often; new files still resolve into the workspace as before.
868
+
869
+ ## [3.4.2] - 2026-09-19
870
+
871
+ `media=` everywhere, CSV / text / Excel attachments, and structured output
872
+ on models that need the Responses API. Non-breaking.
873
+
874
+ ### Added
875
+
876
+ - **`media=` on chat models and structured output.** `llm.invoke`,
877
+ `llm.ainvoke`, and `with_structured_output(...).invoke` / `.ainvoke` take
878
+ `media=[...]` (paths, URLs, `Media`, part dicts), appended to the last
879
+ user turn, matching the agent runner. Media inside `content` lists
880
+ already worked; this adds the argument.
881
+ - **CSV, text files, and Excel in `media=`.** Text-like files (CSV, TSV,
882
+ TXT, Markdown, JSON, XML, YAML, HTML) are read as text -- exactly as
883
+ written, UTF-8 or Windows-1252, CRLF normalised -- and spreadsheets
884
+ (.xlsx / .xls / .ods) are converted with pandas (`dtype=object`, so
885
+ cell values aren't re-inferred) to one CSV block per sheet. Both reach
886
+ GPT (chat and Responses) and Claude as a labelled text block, which
887
+ every model accepts. New `Media.text()` / `Media.spreadsheet()`; a
888
+ 100,000-character cap (`max_chars=`, `truncate=True`). pandas and
889
+ openpyxl are now core dependencies, so spreadsheets work after a plain
890
+ `pip install agentx-dev` (`[excel]` still works). Date cells without a
891
+ time are written as dates, not `... 00:00:00`.
892
+ - **Media docs section.** Its own nav group: Overview & flow, With chat
893
+ models, With agents, Reference (constructors, per-provider wire
894
+ formats, errors). `docs/guides/media.md` is now a pointer to it.
895
+
896
+ ### Fixed
897
+
898
+ - **`with_structured_output` on models that need the Responses API.**
899
+ Structured output forces a single tool; if the Responses API rejects a
900
+ forced tool choice for the model, `GPT` retries with
901
+ `tool_choice="required"` (the same tool when there is only one), then
902
+ `"auto"`, remembering it per model. `StructuredOutputRunnable` also
903
+ accepts a JSON text answer that validates against the schema.
904
+ - **`.txt` media failed on Claude.** 3.4.0 stored text files as base64
905
+ documents, which Anthropic only accepts for PDFs. Text files now go
906
+ out as text; older base64 text parts in saved histories are decoded
907
+ on the way out.
908
+ - **Unsupported files reached the provider.** `Media.document()`
909
+ accepted any file type -- including CSV, which Windows' own type table
910
+ labels `application/vnd.ms-excel` -- and sent it as an attachment
911
+ neither provider accepts. Word, PowerPoint and archives now raise
912
+ `ValueError` with the fix before any request; a text file or
913
+ spreadsheet by URL raises too, since only PDFs can be fetched by URL.
914
+ - **Misleading WARNING on recovered calls.** The retry wrapper logged
915
+ every non-retryable 400 at WARNING before the caller could recover, so a
916
+ call that switched to the Responses API and succeeded still printed the
917
+ original "Function tools with reasoning_effort are not supported" text.
918
+ Now DEBUG; recoveries log their own WARNING and real failures log ERROR.
919
+
920
+ ## [3.4.1] - 2026-09-18
921
+
922
+ Tool calls on OpenAI models that require the Responses API.
923
+
924
+ ### Fixed
925
+
926
+ - **Tool calls failed on models that need the Responses API.** Some
927
+ OpenAI models (e.g. `gpt-6-astra`) reject function tools combined with
928
+ reasoning on `/v1/chat/completions`, and the error's suggested fix --
929
+ `reasoning_effort='none'` -- is itself rejected by those models, so
930
+ 3.4.0's parameter adaptation had nowhere to go. `GPT` now switches a
931
+ model's tool calls to `/v1/responses` when the provider says to,
932
+ retries, and remembers it (WARNING-logged). History is translated only
933
+ at the wire (`function_call` / `function_call_output` items paired by
934
+ `call_id`), so agents, `tool_calls`, and completions are unchanged.
935
+ Learned parameter fixes carry across endpoints (`reasoning.effort` maps
936
+ to `reasoning_effort`). Requests are sent with `store=False`, matching
937
+ chat completions. Plain text calls and streaming stay on chat
938
+ completions.
939
+ - Requests chat completions can't express (a document URL) go to the
940
+ Responses API, which accepts `file_url`, instead of raising.
941
+
942
+ ### Added
943
+
944
+ - `GPT(use_responses_api=None | True | False)`: automatic (default),
945
+ always, or never.
946
+
947
+ ## [3.4.0] - 2026-09-18
948
+
949
+ Media input for GPT and Claude, models that adapt to each generation's
950
+ parameter support, and workspace-rooted paths. Non-breaking; two
951
+ defaults changed -- see docs/guides/upgrading.md.
952
+
953
+ ### Added
954
+
955
+ - **Media input for GPT and Claude.** New `Media` type
956
+ (`Media.image()`, `.document()`, `.audio()`, `.from_path()`,
957
+ `.from_url()`, `.from_bytes()`) and a `media=[...]` argument on
958
+ `AgentRunner.invoke` / `stream` and `AsyncAgentRunner.ainvoke` /
959
+ `astream`. Items can be paths, URLs, `Media`, or content-part dicts
960
+ in either provider's native shape; each model renders them in its
961
+ own wire format (OpenAI `image_url` / `file` / `input_audio`,
962
+ Anthropic `image` / `document`). Unsupported combinations -- audio to
963
+ Claude, a document URL to GPT -- raise `ValueError` before any
964
+ request. Media is stored as plain JSON dicts, so `completion.history`
965
+ and `Session.save()` keep working. Guide: docs/guides/media.md.
966
+
967
+ - **Models adapt to per-generation parameter support.** `GPT` and
968
+ `Claude` read a parameter-compatibility 400 (which names the
969
+ parameter and, for enums, the allowed values), make the smallest
970
+ change it asks for, retry, and remember it per model: an unsupported
971
+ `reasoning_effort` moves to the nearest supported value, `max_tokens`
972
+ becomes `max_completion_tokens` on reasoning models (up front for
973
+ known families), parameters a model lacks are dropped, and Claude's
974
+ `max_tokens` is clamped to the model's cap. Logged at WARNING; other
975
+ 400s raise unchanged. `adapt_params=False` opts out.
976
+
977
+ - **`Claude` gains `top_p`, `top_k`, `thinking`, `stop_sequences`.**
978
+
979
+ ### Changed
980
+
981
+ - `Claude(temperature=)` defaults to `None` (not sent; the API default is
982
+ the old 1.0). Always sending it conflicted with `top_p` on newer models
983
+ and with extended thinking.
984
+ - `GPT(reasoning_effort=)` accepts any string, not just
985
+ `none | low | medium | high`, so `minimal` and `xhigh` are expressible.
986
+
987
+ ### Fixed
988
+
989
+ - **`reasoning_effort="none"` crashed on models that don't take it**
990
+ ("Unsupported value: 'reasoning_effort' does not support 'none' with
991
+ this model"). The models docs even recommended `"none"` as a fix for
992
+ tool-calling conflicts; that advice is gone.
993
+ - **Workspace-rooted paths resolved to the drive root.** With a workspace
994
+ set, `/bruce.jpeg` became `C:\bruce.jpeg` on Windows (a leading slash
995
+ with no drive means the current drive's root) and the sandbox rejected
996
+ it. A leading slash now means the workspace root; the re-rooted path
997
+ is still sandbox-checked, so traversal is rejected as before.
998
+ - **`run_python` ran in the host process's directory, not the
999
+ workspace.** It passed no `cwd`, so `open("bruce.jpeg")` looked
1000
+ wherever the program was launched from. It now starts in the workspace,
1001
+ matching `run_shell`.
1002
+ - **Message-list input stringified media into the prompt.** A user turn
1003
+ whose content was a list (text + image) went through `str()`, so an
1004
+ attached image reached the model as base64 text. Text and media are
1005
+ now split, and earlier turns keep their list content.
1006
+ - **Claude returned the wrong block with extended thinking.** It read
1007
+ `response.content[0].text`; with thinking the first block is a
1008
+ `thinking` block. Text blocks are now joined.
1009
+ - `GPT.Initialize` / `stream_text` / `astream_text` now run messages
1010
+ through the same OpenAI translator as `call_with_tools`.
1011
+
1012
+ ## [3.3.1] - 2026-09-09
1013
+
1014
+ Correctness fixes in the agent loop, found by driving it with a
1015
+ scripted model rather than reading it. No API changes; every fix
1016
+ replaces a silent wrong answer or a runaway cost with correct
1017
+ behaviour. Nine regression tests ship with them
1018
+ (`tests/test_agent_loop_flaws.py`).
1019
+
1020
+ ### Fixed
1021
+
1022
+ - **Native binding had no loop-level spiral guard.** The repeat breaker
1023
+ sat after the native branch's `continue`, so `bind_tools_natively`
1024
+ runs never reached it: a model stuck re-issuing one call burned the
1025
+ full `max_iterations` (20 LLM turns where text mode stopped at 3) and
1026
+ returned the "hit max_iterations" recap quoting the dup-guard's own
1027
+ warning text instead of the data.
1028
+
1029
+ - **`respond` batched with real tool calls dropped them.** A model that
1030
+ emitted "do X, and here is my answer" in one turn had X silently
1031
+ discarded -- never dispatched, never in `completion.tool_calls`, no
1032
+ error. The batch now runs and the answer defers one turn.
1033
+
1034
+ - **`completion.history` could not be replayed as `chat_history`.** The
1035
+ copy filter kept only truthy `{role, content}`, which dropped every
1036
+ tool-calling assistant turn (`content=""`), stripped `tool_call_id`
1037
+ off `role="tool"` messages, and replayed a stored system prompt on top
1038
+ of the fresh one -- so a follow-up call sent two system messages, zero
1039
+ assistant turns, and an orphaned tool message providers reject. Fixed
1040
+ in both runners.
1041
+
1042
+ - **A sync `AgentRunner` silently ignored async tools.** `known_tools`
1043
+ unioned only the two sync registry tables while the registry accepted,
1044
+ listed and prompt-advertised async ones, so calling one fell through
1045
+ to implicit-final and returned `action_input` as the answer with an
1046
+ empty `tool_calls` list. Now unions all four, matching the async
1047
+ runner; the sync dispatcher already returns a clear `ToolError`, so
1048
+ the silent wrong answer became an actionable one.
1049
+
1050
+ - **`AsyncAgentRunner` regressed the function-calling message shape.**
1051
+ It appended its FC turn as raw JSON text with no `tool_calls` block
1052
+ and never set `_last_function_call_id`, so observations went back as
1053
+ `role="user"` -- text-mode shape while in FC mode, losing provider
1054
+ correlation and the cached prefix.
1055
+
1056
+ - **A `BaseException` from a specialist orphaned its siblings.**
1057
+ `CancelledError` and `KeyboardInterrupt` are not `Exception`, so
1058
+ `_run_subtask`'s handler never saw them; `t.result()` re-raised and
1059
+ left sibling tasks running unowned, with in-flight LLM calls still
1060
+ billing. The scheduler now owns its tasks in a `try`/`finally`, which
1061
+ also covers a consumer that stops iterating `astream` early.
1062
+
1063
+ - **The tool cache collided on tool name.** It is a process-wide
1064
+ singleton keyed on `(tool_name, args)` with no record of which
1065
+ implementation ran, so two runners whose tools merely share a name --
1066
+ `search`, `fetch`, `query`, routine across Supervisor specialists --
1067
+ served each other's results and the second function never ran. Keys
1068
+ now fold in the callable's `module.qualname`, so same-name /
1069
+ different-implementation misses while genuinely identical tools still
1070
+ share, including across processes for the disk-backed `FileCache`.
1071
+
1072
+ ### Docs
1073
+
1074
+ - Streaming documentation described parameters the API rejects.
1075
+ `AsyncAgentRunner.astream()` and `HandoffCoordinator.stream()` take no
1076
+ `stream_tokens` (only the sync `AgentRunner.stream()` does), and every
1077
+ `text_delta` example was built on a default model where
1078
+ `use_function_calling` auto-detects to `True` and yields zero deltas.
1079
+ `simple_stream` was documented with the wrong signature entirely.
1080
+ Added a table naming exactly which stream methods accept what.
1081
+
1082
+ ### Tests
1083
+
1084
+ - Repaired 20 stale text-mode tests. `MockModel` defined
1085
+ `call_with_tools` unconditionally, so 3.1.7's auto-detect routed every
1086
+ text script down the function-calling path and the runner returned
1087
+ `""`. The mock now advertises the capability only when scripted for
1088
+ it. Suite: 206 passed, 3 skipped.
1089
+
1090
+ ## [3.3.0] - 2026-08-19
1091
+
1092
+ Dependency DAGs for the Supervisor. Plans declare which steps consume
1093
+ which, and the executor derives ordering, parallelism, AND context
1094
+ routing from those edges — unifying the old split where sequential
1095
+ mode had threading but no parallelism and concurrent mode had
1096
+ parallelism but no threading. Design: docs/design/3.3-depends-on-dag.md.
1097
+
1098
+ ### Added
1099
+
1100
+ - **`depends_on` plan steps.** Every plan step now carries an `id`;
1101
+ a step that consumes an earlier step's output lists that id in
1102
+ `depends_on`. Sync `Supervisor` executes in stable topological
1103
+ order; `AsyncSupervisor` runs a completion-driven scheduler where a
1104
+ step starts the MOMENT its dependencies finish (not on wave
1105
+ barriers) and independent steps run concurrently. In DAG mode each
1106
+ step is threaded ONLY its direct dependencies' results — explicit
1107
+ routing instead of "everything prior", which also stops the
1108
+ per-entry context budget shrinking as plans grow.
1109
+
1110
+ - **Plan sanitization that never fails a run.** Missing/duplicate ids
1111
+ auto-assigned, unknown dependencies dropped (a planner typo degrades
1112
+ to a root step, not a dead run), self-deps dropped, cycles broken
1113
+ deterministically (back-edge in plan order), spawn steps cannot be
1114
+ depended on. If repairs were needed, the plan is re-requested once
1115
+ (`max_plan_retries`, default 1) with the repair warnings appended;
1116
+ the sanitized original is kept when the retry is no better.
1117
+
1118
+ - **Failure cascade + `skipped` flag.** A step whose dependency failed
1119
+ (after retries / success-check) is skipped, transitively, with
1120
+ `SubtaskResult.skipped=True` and an error naming the failed dep.
1121
+ Independent branches keep running; synthesis runs over what
1122
+ succeeded. Skipped steps never dispatch — no tokens burned
1123
+ downstream of garbage.
1124
+
1125
+ - **`skip_when` conditional execution.** A step may declare
1126
+ `{"step": <direct dep id>, "field": <typed output field>, "is": <value>}`;
1127
+ evaluated in Python (no LLM call) against the dependency's 3.2
1128
+ structured output, dotted paths supported, strictly FAIL-OPEN (any
1129
+ doubt → the step runs). Condition-skips do NOT cascade — dependents
1130
+ treat them as empty successes ("retrieval unnecessary" is not
1131
+ "answering impossible").
1132
+
1133
+ - **`Specialist` registry entries.** `agents={}` now also accepts
1134
+ `Specialist(description, runner, depends_on=[...names...],
1135
+ output_schema=..., when_to_use=...)`. The extras render into the
1136
+ planning catalog (`typically after:` / `returns: Schema(fields)` /
1137
+ `use when:`) so the planner can write real dependency graphs and
1138
+ `skip_when` conditions against actual field names. `depends_on`
1139
+ here is a planner HINT, never an execution constraint (the same
1140
+ specialist can appear twice in one plan; step-ids disambiguate).
1141
+ Classic `(description, runner)` tuples keep working — they are
1142
+ wrapped internally, and `Specialist` tuple-unpacks for older code.
1143
+
1144
+ - **`AsyncSupervisor(max_parallel=N)`.** Caps concurrent sub-tasks for
1145
+ rate-limited deployments. `sequential=True` is now sugar for
1146
+ `max_parallel=1` with all-prior threading.
1147
+
1148
+ - **`SubtaskResult.step_id` / `.depends_on` / `.skipped`** and a
1149
+ `step_id` field on `dispatch` / `subtask_result` stream events.
1150
+
1151
+ ### Backward compatibility
1152
+
1153
+ A plan where NO step declares `depends_on` runs with byte-identical
1154
+ legacy semantics: sync + async-sequential thread all prior results in
1155
+ plan order; async-concurrent runs everything at once with no
1156
+ threading. Verified by regression tests against the 3.2 behaviour.
1157
+
1158
+ ## [3.2.0] - 2026-08-13
1159
+
1160
+ Typed multi-agent pipelines. Specialists can now declare a Pydantic
1161
+ output schema once and pass validated instances to each other through
1162
+ the Supervisor, instead of downstream agents re-parsing prose.
1163
+
1164
+ ### Added
1165
+
1166
+ - **`output_schema` on the `AgentRunner` / `AsyncAgentRunner`
1167
+ constructor.** Declare the runner's output shape once
1168
+ (`AgentRunner(..., output_schema=QueryIntent)`) instead of passing it
1169
+ on every call or describing JSON in the prompt. A per-call
1170
+ `output_schema=` still wins when both are set. `None` keeps the exact
1171
+ pre-3.2 behaviour: no coercion, `completion.output` stays `None`.
1172
+
1173
+ - **Schema coercion via forced native function calling.** When a schema
1174
+ is in play, the final answer is converted by forcing a provider-native
1175
+ tool call against the schema (constrained decoding), not by regexing
1176
+ JSON out of prose. The ReAct loop itself is untouched: tool selection
1177
+ and intermediate reasoning run exactly as before, and the coercion
1178
+ happens once, after the loop finishes. Models without a
1179
+ `call_with_tools` implementation fall back to the previous text-JSON
1180
+ parsing, so custom `BaseChatModel` subclasses keep working.
1181
+ `completion.content` keeps the human-readable answer alongside
1182
+ `completion.output` in every case.
1183
+
1184
+ - **`SubtaskResult.output`.** The Supervisor now preserves each
1185
+ specialist's validated Pydantic instance next to its `content` text.
1186
+ Consumers that only read `content` are unaffected.
1187
+
1188
+ - **Structured specialist-to-specialist handoff.** When an earlier step
1189
+ produced typed output, `_build_augmented_query` serializes it into the
1190
+ next specialist's context as a labelled JSON block
1191
+ (`STRUCTURED OUTPUT (QueryIntent): {...}`) followed by the summary
1192
+ text, so downstream steps parse fields rather than interpreting
1193
+ sentences like `INTENT: ... SEARCH_QUERY: ...`.
1194
+
1195
+ - **`vector_search_tool` pipeline options.** New kwargs:
1196
+ `max_text_chars` (default 500; pass `0` for full untruncated passages,
1197
+ which a reranker judging evidence actually needs) and
1198
+ `structured_output` (default False; when True the tool returns a JSON
1199
+ array of `{id, text, vector_score, metadata}` instead of the
1200
+ human-formatted list). Defaults preserve existing behaviour byte-for-
1201
+ byte.
1202
+
1203
+ ### Fixed
1204
+
1205
+ - **Supervisor planning prompt contradicted the execution engine.** The
1206
+ planner rule said sub-agents "do NOT see previous steps' output" and
1207
+ discouraged dependency chains, but the dispatcher has threaded prior
1208
+ findings into every step since `_build_augmented_query` shipped.
1209
+ The rule now tells the planner that sequential steps receive earlier
1210
+ results (structured when available) and that chains like
1211
+ intent -> retrieval -> reranking are a good plan shape, while still
1212
+ requiring same-specialist steps to merge and banning report-only steps.
1213
+
1214
+ ## [3.1.7] — 2026-07-27
1215
+
1216
+ ### Changed
1217
+
1218
+ - **`use_function_calling` default flipped to auto-detect** on
1219
+ `AgentRunner` / `AsyncAgentRunner`. The parameter's default type is
1220
+ now `Optional[bool] = None`; `None` resolves to `True` when the
1221
+ model class overrides `BaseChatModel.call_with_tools` (both `GPT`
1222
+ and `Claude` do) and to `False` when it doesn't (or when
1223
+ `bind_tools_natively=True`). Callers passing `True`/`False`
1224
+ explicitly are unaffected. Rationale: text-mode ReAct requires the
1225
+ model to emit strict JSON with any long `action_input` string
1226
+ properly escaped — a 1200-word markdown draft with unescaped
1227
+ newlines or quotes reliably breaks `json.loads` and killed the run.
1228
+ Function-calling mode routes the parser through the SDK's typed
1229
+ channel so escaping is handled automatically. The historical
1230
+ default (`False`) was the fragile option; the new default matches
1231
+ what most users actually want.
1232
+
1233
+ ### Fixed
1234
+
1235
+ - **Malformed parser JSON no longer crashes the run.** When the
1236
+ text-mode assistant response failed `json.loads` (typically because
1237
+ a long `action_input` string had unescaped `"`, `\n`, or backticks),
1238
+ the framework used to raise `JSONDecodeError` and unwind the whole
1239
+ invocation. The runner now (1) tries a regex-based salvage that
1240
+ extracts `{Thought, action, action_input}` from the raw text
1241
+ covering the common "outer envelope valid, inner string broke
1242
+ escaping" failure, and (2) if salvage fails, feeds a targeted fix
1243
+ hint back to the model (`"your last response was not valid JSON;
1244
+ emit …, escape newlines as \n"`) and continues the loop bounded
1245
+ by `max_iterations`. Exhaustion returns a clear framework message
1246
+ rather than an uncaught exception. Applied to both sync and async
1247
+ runners via a shared `_salvage_react_json` helper.
1248
+ The salvager's action-name regex is intentionally strict
1249
+ (`[A-Za-z_][A-Za-z0-9_.\- ]{0,79}`) so it can't hallucinate an
1250
+ "action" out of an unrelated `"key":"value"` pair inside malformed
1251
+ JSON.
1252
+
1253
+ - **Verbose trace in `bind_tools_natively` mode now prints tool
1254
+ name + args + response.** Previously native runs showed blank
1255
+ `[tool.call.start]` / `[tool.call.complete]` pairs (the
1256
+ observability layer fires them without the trace context), so you
1257
+ couldn't tell which tool the model actually invoked or what came
1258
+ back. The runner now prints `[tool] Invoking '<name>' with args:
1259
+ <input>` and `[tool] Response: <preview>` (or `[tool] Error: ...`
1260
+ when the dispatch raised) in the post-dispatch loop, matching the
1261
+ format text-mode and function-calling mode use. Mirrored to the
1262
+ async runner.
1263
+
1264
+ - **`web_fetch_tool(vector_store=...)` auto-ingests fetched pages into
1265
+ a vector store** instead of dumping raw HTML into the model's
1266
+ context. Fixes the TPM-limit trap: when a research agent fetches
1267
+ four articles in parallel (via ``multi_tool_use.parallel`` or
1268
+ native binding), the combined bodies can easily exceed 40k tokens
1269
+ and blow past a 30k TPM ceiling on the very next model call.
1270
+ New parameters on ``web_fetch_tool``:
1271
+
1272
+ | Kwarg | Default | Effect |
1273
+ |---|---|---|
1274
+ | ``vector_store`` | ``None`` | When set, each fetch is HTML-stripped, chunked with ``TextSplitter``, embedded via the store's embeddings, and added with ``{src: url, chunk_index, total_chunks}`` metadata. The tool response becomes a compact summary (URL, byte count, chunk count, 240-char preview) — NOT the raw body. The model then calls ``vector_search`` / ``Rag`` to pull only the passages it needs. |
1275
+ | ``chunk_size`` | ``1500`` | Characters per chunk when ``vector_store`` is set. Ignored otherwise. |
1276
+ | ``chunk_overlap`` | ``200`` | Overlap between adjacent chunks so a fact spanning a boundary is still retrievable. Ignored otherwise. |
1277
+
1278
+ Backwards-compatible: the positional ``cache_dir`` signature keeps
1279
+ working; `web_fetch_tool()` with no ``vector_store`` returns raw
1280
+ body as before. Ingest and cache_dir compose — enable both and get
1281
+ disk-cached full bodies AND searchable chunks. HTML stripping is
1282
+ minimal and dependency-free (regex-based: script/style blocks
1283
+ dropped whole, then tags stripped, whitespace collapsed) so the
1284
+ ingest path adds no new install dependency. On JSON/plain-text
1285
+ responses the stripper is a near no-op.
1286
+
1287
+ The observation returned to the model shows topical coverage --
1288
+ first, middle, and last chunk previews (up to 3 samples,
1289
+ deduplicated for short pages) -- so the model can tell what
1290
+ topics the page actually covers, not just the intro paragraph.
1291
+ Without this the model would only see the page's opening and
1292
+ wouldn't know to query for topics discussed later in the same
1293
+ page. Explicit instruction in the observation ("query with
1294
+ SPECIFIC keywords from the topics above; do NOT re-fetch; do
1295
+ NOT ask for the full body") steers the model toward the RAG path
1296
+ on follow-up turns.
1297
+
1298
+ - **`multi_tool_use.parallel` now reaches its dispatch path.**
1299
+ When GPT wanted to batch several tool calls into one turn (fetch N
1300
+ URLs concurrently, run M searches at once), it emitted OpenAI's
1301
+ synthetic `multi_tool_use.parallel` meta-tool. The registry's
1302
+ `_dispatch_multi_parallel` / `_adispatch_multi_parallel` handlers
1303
+ already knew how to unpack it, but the runner loop's known-tools
1304
+ guardrail rejected the name FIRST as unregistered — dumping the
1305
+ raw `{"tool_uses": [...]}` payload into the user-facing "final
1306
+ answer" and never invoking any of the nested calls. Added
1307
+ `multi_tool_use.parallel` to the recognized action set in both
1308
+ sync and async runners so the meta-tool flows through to dispatch
1309
+ and the existing unpackers run. Nested calls with the `functions.`
1310
+ prefix are normalized before dispatch (same as top-level FC
1311
+ calls), so the model can emit either shape.
1312
+
1313
+ - **`Permissions.full_access` / `read_only` auto-wrap a bare string.**
1314
+ Passing `full_access("./workspace")` used to iterate the string
1315
+ into 11 single-character "subtrees" (Python's `list("./workspace")`)
1316
+ — every path check silently rejected because no real path could
1317
+ ever match a `"."` or `"/"` "allowed subtree". The classmethod
1318
+ now detects a bare string and treats it as `[allowed_paths]`, so
1319
+ `full_access("./workspace")` does the intuitive thing (equivalent
1320
+ to `full_access(["./workspace"])` and auto-infers the workspace).
1321
+ Same fix on `read_only`. List inputs are unchanged.
1322
+
1323
+ - **`Permissions.full_access` now accepts (and auto-infers)
1324
+ `workspace`.** The classmethod set `allowed_paths` but not
1325
+ `workspace`, so short paths like `write_file(path="report.md")`
1326
+ resolved to CWD (outside the sandbox) and raised
1327
+ `PermissionError: access denied` — a landmine that every caller of
1328
+ `Permissions.full_access(["./workspace"])` hit sooner or later.
1329
+ New signature: `full_access(allowed_paths, *, workspace=None)`.
1330
+ When `workspace` isn't passed AND `allowed_paths` has exactly one
1331
+ entry, that path is auto-set as the workspace (the "project-scoped
1332
+ agent whose one allowed subtree IS its workspace" case, which is
1333
+ 99% of use). Two or more paths stay ambiguous and require an
1334
+ explicit `workspace=` if short-path resolution is wanted. Pass an
1335
+ explicit `workspace=` string to override the auto-choice.
1336
+ Backwards-compatible on the positional signature; adds a keyword
1337
+ argument that existing callers didn't use.
1338
+
1339
+ ## [3.1.5] — 2026-07-26
1340
+
1341
+ ### Fixed
1342
+
1343
+ - **Text-mode tool results no longer use `role: "function"`.** In text
1344
+ mode (the default — no `use_function_calling`) the runner fed each tool
1345
+ observation back to the model as a `role: "function"` message. Newer
1346
+ OpenAI models reject that role outright (`400 … 'messages[N].role' does
1347
+ not support 'function' with this model`, e.g. gpt-5.x), and Anthropic
1348
+ never accepted it — text-mode multi-tool runs on Claude were latently
1349
+ broken too; older GPT models simply still tolerated the legacy role.
1350
+ Tool observations now go back as a plain `role: "user"` turn framed as
1351
+ `Observation: …`, which every provider and model generation accepts and
1352
+ which matches the ReAct template's own few-shot convention.
1353
+ Function-calling mode is unchanged (native `role: "tool"` +
1354
+ `tool_call_id`). The async runner was additionally emitting `function`
1355
+ unconditionally (even in FC mode); it now uses the same shared helper.
1356
+
1357
+ ### Added
1358
+
1359
+ - **`subtask_success_check` on `Supervisor` / `AsyncSupervisor`.** Opt-in
1360
+ predicate `(SubtaskResult) -> bool | str` that decides whether a
1361
+ *returned* (non-raised) sub-task result is actually acceptable — the
1362
+ "ran fine but produced nothing useful" case a plain retry can't catch
1363
+ (a scraper that saved 0 links, an extractor that found nothing). Return
1364
+ `True` to accept, or `False`/a `str` reason to reject; a rejected
1365
+ result is retried like a raised error, with the reason fed back into the
1366
+ query, bounded by `max_subtask_retries`. After retries are exhausted the
1367
+ last result is returned with its `error` set (content preserved). A
1368
+ check that itself raises is treated as "accept" so a buggy predicate
1369
+ can't wedge the run. Default `None` keeps the exceptions-only behavior.
1370
+ New example `examples/robust_link_scraper.py` wires it together with a
1371
+ scraping `system_addendum` (parse relative+absolute hrefs, fall back to
1372
+ `sitemap.xml` on JS-rendered sites).
1373
+
1374
+ ## [3.1.4] — 2026-07-26
1375
+
1376
+ ### Fixed
1377
+
1378
+ - **A malformed-JSON tool argument no longer crashes the whole agent
1379
+ run.** When a model emitted a Python snippet or a Windows path as a
1380
+ tool-call argument — `re.findall(r'\d+')`, `C:\Users` — the `\d` / `\U`
1381
+ are illegal JSON escapes, and the OpenAI adapter's eager
1382
+ `json.loads(call.function.arguments)` raised `JSONDecodeError` and
1383
+ `raise`d it, unwinding the entire ReAct loop before the agent's own
1384
+ retry machinery could act. Under a Supervisor this surfaced as a bare
1385
+ `ERROR: Invalid \escape: line 1 column 598` and the sub-task was
1386
+ abandoned. Now:
1387
+ - `_parse_tool_arguments` repairs the common case (backslashes that
1388
+ don't begin a valid JSON escape are doubled), recovering `\d`,
1389
+ `\w`, `\s`, etc. with zero extra round-trips. A backslash before a
1390
+ valid-escape letter (`\b`, `\n`, …) remains ambiguous and is left
1391
+ as the escape — a documented limit.
1392
+ - When repair fails, `call_with_tools` returns a dedicated
1393
+ `invalid_tool_args` result and the loop feeds the error back as a
1394
+ retryable observation ("your arguments weren't valid JSON — escape
1395
+ backslashes and resend"), bounded by `max_iterations`, in all
1396
+ three modes across both `AgentRunner` and `AsyncAgentRunner`.
1397
+ `Claude` was already immune (its tool inputs arrive pre-parsed).
1398
+
1399
+ - **A tool-call preamble is no longer returned as the final answer.**
1400
+ Models routinely end a turn with an announcement instead of an action
1401
+ — "I'll look up your recent scores to get a clear view of your
1402
+ communication skills. Just a second!" — and every "no tool call
1403
+ found" branch in both runners was coded as *this text is the answer,
1404
+ break*. The loop terminated on iteration 1 and the caller got a
1405
+ promise instead of a result. Three sites per runner were affected:
1406
+ the native-binding path (`type != "tool_use"`), the
1407
+ `use_function_calling` path (parser unresolved), and the JSON-text
1408
+ path (response didn't parse). `max_iterations` never helped, because
1409
+ the break happened before any iteration was spent.
1410
+
1411
+ The runner now feeds the model one corrective nudge — "your last turn
1412
+ had no action, so nothing happened; do it, don't announce it" — and
1413
+ continues the loop. Verified against both `AgentRunner` and
1414
+ `AsyncAgentRunner` in all three modes.
1415
+
1416
+ ### Added
1417
+
1418
+ - **Proactive "act, don't announce" system-prompt clause.** The reactive
1419
+ `text_turn_nudges` fix corrects an agent *after* it narrates instead of
1420
+ acting; this clause heads it off. When (and only when) an agent has
1421
+ tools, its system prompt now tells it to call the tool rather than
1422
+ reply "I'll do X / just a second" and stop — and to report what it DID
1423
+ in past tense. Injected in all three modes across both runners; skipped
1424
+ for tool-less chat agents, where prose is the correct answer. Sits
1425
+ before any `system_addendum` so a caller's role instructions still win.
1426
+
1427
+ - **`max_subtask_retries` on `Supervisor` / `AsyncSupervisor`** (default
1428
+ `1`). A sub-task that raised used to be recorded as an error and the
1429
+ Supervisor moved straight to synthesis — no second attempt. Now a
1430
+ failed sub-task is re-dispatched up to this many times, with the prior
1431
+ error appended to the query so the specialist knows what to fix
1432
+ ("your previous attempt failed with X — diagnose and try again").
1433
+ Bounded and informed: only raised exceptions trigger a retry (a
1434
+ sub-task that returns content is accepted as-is, since the Supervisor
1435
+ can't tell "terse but correct" from "wrong"), and the error text is
1436
+ fed back rather than blindly re-running. Set to `0` for the old
1437
+ quit-on-first-failure behavior. Applies in both sequential and
1438
+ concurrent async modes.
1439
+
1440
+ - **`text_turn_nudges` on `AgentRunner` / `AsyncAgentRunner`** (default
1441
+ `1`). Caps the re-prompts described above at one extra LLM call per
1442
+ run; after the budget is spent the model's text stands as the answer.
1443
+ Set to `0` for the previous behavior. Automatically skipped when no
1444
+ tools are registered, since a runner with no tools is a plain chat
1445
+ call and prose genuinely is the answer there.
1446
+
1447
+ ## [3.1.3] — 2026-07-22
1448
+
1449
+ Docs-only patch. No code changes since 3.1.2. Users on 3.1.2 don't
1450
+ need to upgrade for functionality; upgrade to pick up the improved
1451
+ onboarding docs bundled in the sdist.
1452
+
1453
+ ### Documentation
1454
+
1455
+ - **Tools doc rewritten to answer "how do I actually use these?"**
1456
+ Added §0 `How each built-in tool is registered` as the entry
1457
+ section. Two registration paths — auto vs manual — laid out in a
1458
+ table on the first screen. Six runnable subsections covering every
1459
+ combination:
1460
+ - §0.1 DefaultTools via `Permissions(...)` (auto)
1461
+ - §0.2 WebTools via `tools=[web_search_tool(), web_fetch_tool()]`
1462
+ - §0.3 RAG via `TextSplitter` -> `VectorStore.add_documents` ->
1463
+ `vector_search_tool(store)`
1464
+ - §0.4 Handoffs via `handoff_tool` + `HandoffCoordinator`
1465
+ - §0.5 Custom `StructuredTool` from scratch
1466
+ - §0.6 Fully-loaded runner combining all of the above
1467
+ - §0.7 Rules on name collisions, invisible-denied-capabilities,
1468
+ async-tool behavior
1469
+ The existing inventory + wrapper / controls / cheat-sheet sections
1470
+ are unchanged; they now sit after the "how to use them" primer
1471
+ instead of before it.
1472
+
1473
+ ## [3.1.2] — 2026-07-22
1474
+
1475
+ Patch release. Two independent fixes.
1476
+
1477
+ ### Fixed
1478
+
1479
+ - **`llm_judge` correctly parses YES/NO across providers.** The judge
1480
+ parser was comparing the reply's first word to the literal string
1481
+ `"YES"`. GPT-4o answers `"YES,"` (comma-suffixed), which failed the
1482
+ equality check and marked every genuine PASS as FAIL. Claude replies
1483
+ `"YES"` without punctuation so the bug hid during local development.
1484
+ Fixed by matching `\b(YES|NO)\b` (word-boundary regex, case-
1485
+ insensitive) at the start of the reply. Handles every real shape:
1486
+ `YES`, `YES.`, `YES!`, `YES, exactly right`, `Yes.`, `yes -- reason`.
1487
+ Ambiguous replies (`Maybe`, empty string) still fail closed.
1488
+ - Regression test `test_llm_judge_parses_various_verdict_shapes`
1489
+ covers 8 YES shapes, 5 NO shapes, and 4 ambiguous replies.
1490
+
1491
+ ### Added
1492
+
1493
+ - **`agentx_dev.Tools` is a one-stop tools namespace.** Users no
1494
+ longer need to remember which module each tool lives in:
1495
+
1496
+ ```python
1497
+ from agentx_dev.Tools import (
1498
+ StandardTool, StructuredTool,
1499
+ AsyncStandardTool, AsyncStructuredTool,
1500
+ web_search_tool, web_fetch_tool,
1501
+ vector_search_tool, handoff_tool,
1502
+ DefaultTools, Permissions,
1503
+ )
1504
+ ```
1505
+
1506
+ Both this form and the pre-existing `from agentx_dev import X`
1507
+ form coexist. Implementation uses PEP 562 module `__getattr__`
1508
+ and `__dir__` so re-exports are lazy (no import cost for modules
1509
+ the caller doesn't touch) and show up in IDE autocomplete +
1510
+ `dir(agentx_dev.Tools)`.
1511
+
1512
+ ## [3.1.1] — 2026-07-21
1513
+
1514
+ Second batch of 3.1 features + a full docs + brand pass.
1515
+
1516
+ ### Added
1517
+
1518
+ **Streaming through orchestration**
1519
+ - `Supervisor.stream()` / `AsyncSupervisor.astream()` emit
1520
+ `plan_start` / `plan` / `dispatch` / `subtask_result` /
1521
+ `synthesize_start` / `final` / `completion` events.
1522
+ - `HandoffCoordinator.stream()` / `.astream()` emit `invoke` /
1523
+ `completion` / `handoff` / `final` / `result` events per hop.
1524
+ - Legacy `.run()` / `.arun()` refactored to consume the streams (no
1525
+ code duplication).
1526
+
1527
+ **Prompt optimization — `Compiled`**
1528
+ - New `agentx_dev.Compiler` module.
1529
+ - `Compiled(runner_factory, trainset, ...)` iteratively refines a
1530
+ runner's `system_addendum` against the eval harness. Half of
1531
+ DSPy's power at a tenth of the surface.
1532
+
1533
+ **Anthropic Batch API**
1534
+ - `Claude.batch(requests)` submits many prompts at Anthropic's 50%-off
1535
+ batch rate, polls to completion, returns results in submission order.
1536
+ - Per-request error dicts on failure; token usage funneled into
1537
+ `TokenUsage` so cost tracking stays a single source of truth.
1538
+
1539
+ **Vector store adapters — `agentx_dev.VectorStores`**
1540
+ - `ChromaVectorStore`, `QdrantVectorStore`, `PgVectorStore` — same
1541
+ public shape as the in-memory `VectorStore` (`add` / `search` /
1542
+ `delete` / `clear` / `__len__` / `embeddings`).
1543
+ - `vector_search_tool()` and `SemanticMemory` accept any of them.
1544
+ - SDK imports lazy; friendly `ImportError` when the underlying SDK
1545
+ is missing.
1546
+
1547
+ **Trace viewer (`viewer/`)**
1548
+ - Self-hosted single-page app that reads `FileHook` JSONL and renders
1549
+ a timeline with type/text filters, summary sidebar, JSON drill-down.
1550
+ - Works from `file://`, no server required.
1551
+
1552
+ **Docs site (`host/`)**
1553
+ - Full editorial dark-first design system (JetBrains Mono headings,
1554
+ Inter body, `#B8FF3E` electric-lime accent).
1555
+ - Command palette (`Cmd+K`) with keyboard navigation and live search.
1556
+ - Hero code snippet with hand-tinted syntax highlighting.
1557
+ - Reading progress bar, breadcrumbs, header anchor links.
1558
+ - Sidebar sliding active marker, collapsible groups.
1559
+ - Code copy buttons, language labels.
1560
+ - Right-rail auto-TOC with `IntersectionObserver` scrollspy.
1561
+ - Dark/light theme toggle, persisted.
1562
+ - Cache-busted assets so edits land on refresh without hard-reload.
1563
+
1564
+ **Brand identity (`brand/`)**
1565
+ - Full brand kit: 5 SVG assets (`mark`, `mono`, `wordmark`, `logo-full`,
1566
+ `app-icon`), `BRAND.md` strategy doc, rendered brand-kit HTML deck.
1567
+ - Copy audit dropped "small" (weak) and "LangChain" references from
1568
+ all marketing surfaces.
1569
+ - Favicon wired into docs + trace viewer.
1570
+
1571
+ **Test suite (`tests/`)**
1572
+ - Restored + expanded pytest suite: 127 tests passing (3 skipped for
1573
+ absent optional SDKs).
1574
+ - Coverage: parser + all `AgentType` variants, `ToolRegistry`
1575
+ (dispatch / dup-guard / circuit-breaker / timeout), Permissions
1576
+ (capability gating + sandbox + traversal), budgets (cost / rate /
1577
+ retry / non-retryable HTTP), runner loop (streaming + output_schema
1578
+ + chat history), embeddings + `VectorStore` + `SemanticMemory`,
1579
+ handoffs (bounded hops + history sanitization), evals harness
1580
+ (all assertion helpers + JSON case loaders), vector-store adapter
1581
+ shape conformance.
1582
+
1583
+ **Docs (`docs/`)**
1584
+ - Full docs tree (34 pages), including new pages for:
1585
+ vector store adapters, prompt optimization, batch API, trace viewer,
1586
+ and a **use-cases** landing (13 concrete scenarios with runnable code).
1587
+ - Rewrote **Tools** page to enumerate every built-in tool with args,
1588
+ return shape, capability flag, and use-case guidance.
1589
+ - Rewrote **Agents** page to cover all four orchestration
1590
+ architectures (Solo / Supervisor / Handoffs / Compiled) with
1591
+ decision trees, worked examples, and cheat sheet.
1592
+ - **Agentic RAG chatbot** as use case §13 — multi-query decomposition,
1593
+ parallel retrieval, self-critique, citations, user memory.
1594
+
1595
+ **Examples**
1596
+ - `examples/agentic_rag_demo.py` — the runnable version of the
1597
+ agentic RAG use case. Auto-seeds a KB if none exists, `--demo` flag
1598
+ runs a 3-turn scripted session proving user-notes recall works.
1599
+
1600
+ **Package**
1601
+ - `[chroma]`, `[qdrant]`, `[pgvector]`, `[dev]` extras added.
1602
+ - `[anthropic]` bumped to `>=0.36` (Batch API + prompt cache).
1603
+
1604
+ ### Fixed
1605
+
1606
+ - `AgentRunner._iter_run` in `bind_tools_natively=True` mode uses a
1607
+ minimal system prompt instead of the AgentType template so the
1608
+ ReAct `action/action_input` scaffold no longer fights the native
1609
+ tool interface. Previously produced JSON-blob answers under GPT.
1610
+ - `HandoffCoordinator._sanitize_history_for_next_agent` strips tool
1611
+ and function role messages between hops so tool_call_ids from a
1612
+ previous agent don't leak into the next model's call (OpenAI 400).
1613
+ - Docs site marker positioning uses double-`requestAnimationFrame` +
1614
+ `document.fonts.ready` so the sidebar accent bar lands on the
1615
+ correct row even on a cold font cache.
1616
+ - Primary hero CTA color uses `#doc .hero-cta a.primary` selector to
1617
+ outrank `#doc a` link styling (previously rendered lime-on-lime
1618
+ and was invisible).
1619
+
1620
+ ### Notes
1621
+
1622
+ - Package version bumped from `3.0.6` to `3.1.1`. The 3.1.0 release
1623
+ did not ship publicly — 3.1.1 is the first 3.1-tagged PyPI release
1624
+ and includes both batches of features.
1625
+
1626
+ ## [3.1.0] — internal only (commits 52840e7)
1627
+
1628
+ First batch of 3.1 features. Committed but not released to PyPI.
1629
+ Merged into 3.1.1 for the public release.
1630
+
1631
+ ### Added
1632
+ - Anthropic prompt caching (`Claude(enable_prompt_cache=True)`).
1633
+ - Parallel per-turn tool dispatch in `AgentRunner`
1634
+ (`bind_tools_natively=True`, `parallel_tool_workers`).
1635
+ - Semantic memory (`SemanticMemory`, embeddings-backed retrieval).
1636
+ - RAG core (`Embeddings`, `HashEmbeddings`, `OpenAIEmbeddings`,
1637
+ `VectorStore`, `VectorHit`, `vector_search_tool()`).
1638
+ - Agent-to-agent handoffs (`HandoffRequest`, `handoff_tool`,
1639
+ `HandoffCoordinator`, `HandoffResult`).
1640
+ - Evals harness (`EvalCase`, `EvalRunner`, `EvalReport`, 7 assertion
1641
+ helpers, JSON case loader, `python -m agentx_dev.Evals run` CLI).
1642
+ - `TokenUsage.cache_hit_ratio` property.
1643
+
1644
+ ## [3.0.6] — 2026-03 (baseline)
1645
+
1646
+ Security hardening baseline (SSRF guard on `web_fetch`, HMAC-signed
1647
+ persistent state, scrubbed subprocess env, path sanitizer,
1648
+ `permissions.json` mode 0o600, ReDoS guard on `grep`,
1649
+ `invoke`/`ainvoke` accept bare strings and message lists).