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