dostuff 0.2.12__tar.gz → 0.2.14__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 (181) hide show
  1. {dostuff-0.2.12 → dostuff-0.2.14}/PKG-INFO +17 -7
  2. {dostuff-0.2.12 → dostuff-0.2.14}/README.md +8 -5
  3. {dostuff-0.2.12 → dostuff-0.2.14}/dostuff/agent/call_agent.py +18 -2
  4. {dostuff-0.2.12 → dostuff-0.2.14}/dostuff/agent/loop.py +33 -7
  5. {dostuff-0.2.12 → dostuff-0.2.14}/dostuff/agent/subagents/run.py +5 -3
  6. {dostuff-0.2.12 → dostuff-0.2.14}/dostuff/cli_tui.py +89 -8
  7. {dostuff-0.2.12 → dostuff-0.2.14}/dostuff/config.py +25 -0
  8. {dostuff-0.2.12 → dostuff-0.2.14}/dostuff/headless.py +15 -3
  9. dostuff-0.2.14/dostuff/helpers/agent/attachments.py +407 -0
  10. dostuff-0.2.14/dostuff/helpers/agent/clipboard.py +167 -0
  11. {dostuff-0.2.12 → dostuff-0.2.14}/dostuff/helpers/agent/context_usage.py +19 -4
  12. dostuff-0.2.14/dostuff/helpers/agent/convert_document.py +189 -0
  13. dostuff-0.2.14/dostuff/helpers/agent/file_mentions.py +317 -0
  14. {dostuff-0.2.12 → dostuff-0.2.14}/dostuff/helpers/agent/manage_context.py +17 -5
  15. {dostuff-0.2.12 → dostuff-0.2.14}/dostuff/helpers/agent/steering.py +5 -2
  16. dostuff-0.2.14/dostuff/helpers/agent/tool_attachments.py +87 -0
  17. {dostuff-0.2.12 → dostuff-0.2.14}/dostuff/helpers/hooks/events.py +9 -4
  18. {dostuff-0.2.12 → dostuff-0.2.14}/dostuff/helpers/hooks/run_hook.py +1 -1
  19. {dostuff-0.2.12 → dostuff-0.2.14}/dostuff/helpers/memory/export_session.py +12 -1
  20. {dostuff-0.2.12 → dostuff-0.2.14}/dostuff/lib/memory/session_store.py +4 -0
  21. {dostuff-0.2.12 → dostuff-0.2.14}/dostuff/lib/model.py +17 -1
  22. {dostuff-0.2.12 → dostuff-0.2.14}/dostuff/templates/config.example.yaml +4 -0
  23. dostuff-0.2.14/dostuff/tools/files/read_file.py +80 -0
  24. {dostuff-0.2.12 → dostuff-0.2.14}/dostuff/tools/mcp/call_mcp_tool.py +28 -2
  25. {dostuff-0.2.12 → dostuff-0.2.14}/dostuff.egg-info/PKG-INFO +17 -7
  26. {dostuff-0.2.12 → dostuff-0.2.14}/dostuff.egg-info/SOURCES.txt +5 -0
  27. {dostuff-0.2.12 → dostuff-0.2.14}/dostuff.egg-info/requires.txt +10 -1
  28. {dostuff-0.2.12 → dostuff-0.2.14}/pyproject.toml +13 -2
  29. dostuff-0.2.14/tests/test_attachments.py +1122 -0
  30. {dostuff-0.2.12 → dostuff-0.2.14}/tests/test_cli_commands.py +50 -0
  31. {dostuff-0.2.12 → dostuff-0.2.14}/tests/test_hooks.py +44 -2
  32. {dostuff-0.2.12 → dostuff-0.2.14}/tests/test_loop.py +56 -0
  33. {dostuff-0.2.12 → dostuff-0.2.14}/tests/test_tools_listing.py +1 -1
  34. {dostuff-0.2.12 → dostuff-0.2.14}/tests/test_tui.py +303 -0
  35. dostuff-0.2.12/dostuff/helpers/agent/file_mentions.py +0 -182
  36. dostuff-0.2.12/dostuff/tools/files/read_file.py +0 -46
  37. {dostuff-0.2.12 → dostuff-0.2.14}/LICENSE +0 -0
  38. {dostuff-0.2.12 → dostuff-0.2.14}/dostuff/__init__.py +0 -0
  39. {dostuff-0.2.12 → dostuff-0.2.14}/dostuff/__main__.py +0 -0
  40. {dostuff-0.2.12 → dostuff-0.2.14}/dostuff/agent/instructions.py +0 -0
  41. {dostuff-0.2.12 → dostuff-0.2.14}/dostuff/agent/permissions.py +0 -0
  42. {dostuff-0.2.12 → dostuff-0.2.14}/dostuff/agent/run_tool.py +0 -0
  43. {dostuff-0.2.12 → dostuff-0.2.14}/dostuff/agent/subagents/__init__.py +0 -0
  44. {dostuff-0.2.12 → dostuff-0.2.14}/dostuff/agent/subagents/adapter.py +0 -0
  45. {dostuff-0.2.12 → dostuff-0.2.14}/dostuff/agent/subagents/definitions.py +0 -0
  46. {dostuff-0.2.12 → dostuff-0.2.14}/dostuff/agent/subagents/fork.py +0 -0
  47. {dostuff-0.2.12 → dostuff-0.2.14}/dostuff/agent/subagents/prompt.py +0 -0
  48. {dostuff-0.2.12 → dostuff-0.2.14}/dostuff/agent/subagents/registry.py +0 -0
  49. {dostuff-0.2.12 → dostuff-0.2.14}/dostuff/cli.py +0 -0
  50. {dostuff-0.2.12 → dostuff-0.2.14}/dostuff/helpers/agent/append_step.py +0 -0
  51. {dostuff-0.2.12 → dostuff-0.2.14}/dostuff/helpers/agent/constants.py +0 -0
  52. {dostuff-0.2.12 → dostuff-0.2.14}/dostuff/helpers/agent/consume_stream.py +0 -0
  53. {dostuff-0.2.12 → dostuff-0.2.14}/dostuff/helpers/agent/environment_context.py +0 -0
  54. {dostuff-0.2.12 → dostuff-0.2.14}/dostuff/helpers/agent/get_model_token_limit.py +0 -0
  55. {dostuff-0.2.12 → dostuff-0.2.14}/dostuff/helpers/agent/load_identity.py +0 -0
  56. {dostuff-0.2.12 → dostuff-0.2.14}/dostuff/helpers/agent/load_project_instructions.py +0 -0
  57. {dostuff-0.2.12 → dostuff-0.2.14}/dostuff/helpers/agent/loop_check_cancelled.py +0 -0
  58. {dostuff-0.2.12 → dostuff-0.2.14}/dostuff/helpers/agent/loop_emit.py +0 -0
  59. {dostuff-0.2.12 → dostuff-0.2.14}/dostuff/helpers/agent/model_cost.py +0 -0
  60. {dostuff-0.2.12 → dostuff-0.2.14}/dostuff/helpers/agent/notices.py +0 -0
  61. {dostuff-0.2.12 → dostuff-0.2.14}/dostuff/helpers/agent/pastes.py +0 -0
  62. {dostuff-0.2.12 → dostuff-0.2.14}/dostuff/helpers/agent/quick_memory.py +0 -0
  63. {dostuff-0.2.12 → dostuff-0.2.14}/dostuff/helpers/agent/side_question.py +0 -0
  64. {dostuff-0.2.12 → dostuff-0.2.14}/dostuff/helpers/agent/slash_suggestion.py +0 -0
  65. {dostuff-0.2.12 → dostuff-0.2.14}/dostuff/helpers/agent/tool_output.py +0 -0
  66. {dostuff-0.2.12 → dostuff-0.2.14}/dostuff/helpers/agent/turn_context.py +0 -0
  67. {dostuff-0.2.12 → dostuff-0.2.14}/dostuff/helpers/config_secrets.py +0 -0
  68. {dostuff-0.2.12 → dostuff-0.2.14}/dostuff/helpers/hooks/__init__.py +0 -0
  69. {dostuff-0.2.12 → dostuff-0.2.14}/dostuff/helpers/hooks/dispatch.py +0 -0
  70. {dostuff-0.2.12 → dostuff-0.2.14}/dostuff/helpers/hooks/load_hooks.py +0 -0
  71. {dostuff-0.2.12 → dostuff-0.2.14}/dostuff/helpers/hooks/trust.py +0 -0
  72. {dostuff-0.2.12 → dostuff-0.2.14}/dostuff/helpers/mcp/load_mcp_config.py +0 -0
  73. {dostuff-0.2.12 → dostuff-0.2.14}/dostuff/helpers/mcp/mcp_oauth.py +0 -0
  74. {dostuff-0.2.12 → dostuff-0.2.14}/dostuff/helpers/mcp/server_config.py +0 -0
  75. {dostuff-0.2.12 → dostuff-0.2.14}/dostuff/helpers/mcp/token_store.py +0 -0
  76. {dostuff-0.2.12 → dostuff-0.2.14}/dostuff/helpers/memory/resolve_memory_operation.py +0 -0
  77. {dostuff-0.2.12 → dostuff-0.2.14}/dostuff/helpers/memory/shell_step.py +0 -0
  78. {dostuff-0.2.12 → dostuff-0.2.14}/dostuff/helpers/models/add_model_entry.py +0 -0
  79. {dostuff-0.2.12 → dostuff-0.2.14}/dostuff/helpers/models/list_models.py +0 -0
  80. {dostuff-0.2.12 → dostuff-0.2.14}/dostuff/helpers/models/opencode.py +0 -0
  81. {dostuff-0.2.12 → dostuff-0.2.14}/dostuff/helpers/skills/custom_commands.py +0 -0
  82. {dostuff-0.2.12 → dostuff-0.2.14}/dostuff/helpers/skills/discover_skills.py +0 -0
  83. {dostuff-0.2.12 → dostuff-0.2.14}/dostuff/helpers/skills/skill_command.py +0 -0
  84. {dostuff-0.2.12 → dostuff-0.2.14}/dostuff/helpers/tools/diff.py +0 -0
  85. {dostuff-0.2.12 → dostuff-0.2.14}/dostuff/helpers/tools/generate_tool_schema.py +0 -0
  86. {dostuff-0.2.12 → dostuff-0.2.14}/dostuff/helpers/tools/project_root.py +0 -0
  87. {dostuff-0.2.12 → dostuff-0.2.14}/dostuff/helpers/tools/resolve_safe_path.py +0 -0
  88. {dostuff-0.2.12 → dostuff-0.2.14}/dostuff/helpers/ui/__init__.py +0 -0
  89. {dostuff-0.2.12 → dostuff-0.2.14}/dostuff/helpers/ui/ask_answers.py +0 -0
  90. {dostuff-0.2.12 → dostuff-0.2.14}/dostuff/helpers/ui/doctor.py +0 -0
  91. {dostuff-0.2.12 → dostuff-0.2.14}/dostuff/helpers/ui/emit.py +0 -0
  92. {dostuff-0.2.12 → dostuff-0.2.14}/dostuff/helpers/ui/prompt_history.py +0 -0
  93. {dostuff-0.2.12 → dostuff-0.2.14}/dostuff/helpers/ui/terminal_signals.py +0 -0
  94. {dostuff-0.2.12 → dostuff-0.2.14}/dostuff/helpers/ui/tools_listing.py +0 -0
  95. {dostuff-0.2.12 → dostuff-0.2.14}/dostuff/lib/checkpoints.py +0 -0
  96. {dostuff-0.2.12 → dostuff-0.2.14}/dostuff/lib/exceptions.py +0 -0
  97. {dostuff-0.2.12 → dostuff-0.2.14}/dostuff/lib/mcp/mcp_client.py +0 -0
  98. {dostuff-0.2.12 → dostuff-0.2.14}/dostuff/lib/mcp/mcp_client_registration_store.py +0 -0
  99. {dostuff-0.2.12 → dostuff-0.2.14}/dostuff/lib/mcp/mcp_tool_registry_store.py +0 -0
  100. {dostuff-0.2.12 → dostuff-0.2.14}/dostuff/lib/memory/chroma.py +0 -0
  101. {dostuff-0.2.12 → dostuff-0.2.14}/dostuff/lib/memory/episodic_memory_store.py +0 -0
  102. {dostuff-0.2.12 → dostuff-0.2.14}/dostuff/lib/memory/semantic_memory_store.py +0 -0
  103. {dostuff-0.2.12 → dostuff-0.2.14}/dostuff/lib/memory/stores.py +0 -0
  104. {dostuff-0.2.12 → dostuff-0.2.14}/dostuff/lib/memory/types.py +0 -0
  105. {dostuff-0.2.12 → dostuff-0.2.14}/dostuff/lib/tracing.py +0 -0
  106. {dostuff-0.2.12 → dostuff-0.2.14}/dostuff/lib/worktree.py +0 -0
  107. {dostuff-0.2.12 → dostuff-0.2.14}/dostuff/memory/__init__.py +0 -0
  108. {dostuff-0.2.12 → dostuff-0.2.14}/dostuff/setup_wizard.py +0 -0
  109. {dostuff-0.2.12 → dostuff-0.2.14}/dostuff/skills.py +0 -0
  110. {dostuff-0.2.12 → dostuff-0.2.14}/dostuff/templates/env.example +0 -0
  111. {dostuff-0.2.12 → dostuff-0.2.14}/dostuff/tools/__init__.py +0 -0
  112. {dostuff-0.2.12 → dostuff-0.2.14}/dostuff/tools/agent.py +0 -0
  113. {dostuff-0.2.12 → dostuff-0.2.14}/dostuff/tools/ask_user.py +0 -0
  114. {dostuff-0.2.12 → dostuff-0.2.14}/dostuff/tools/bash/bash_command.py +0 -0
  115. {dostuff-0.2.12 → dostuff-0.2.14}/dostuff/tools/bash/bash_output.py +0 -0
  116. {dostuff-0.2.12 → dostuff-0.2.14}/dostuff/tools/bash/jobs.py +0 -0
  117. {dostuff-0.2.12 → dostuff-0.2.14}/dostuff/tools/bash/kill_shell.py +0 -0
  118. {dostuff-0.2.12 → dostuff-0.2.14}/dostuff/tools/create_agent_type.py +0 -0
  119. {dostuff-0.2.12 → dostuff-0.2.14}/dostuff/tools/definitions.py +0 -0
  120. {dostuff-0.2.12 → dostuff-0.2.14}/dostuff/tools/files/delete_file.py +0 -0
  121. {dostuff-0.2.12 → dostuff-0.2.14}/dostuff/tools/files/edit_file.py +0 -0
  122. {dostuff-0.2.12 → dostuff-0.2.14}/dostuff/tools/files/list_files.py +0 -0
  123. {dostuff-0.2.12 → dostuff-0.2.14}/dostuff/tools/files/multi_edit.py +0 -0
  124. {dostuff-0.2.12 → dostuff-0.2.14}/dostuff/tools/files/write_file.py +0 -0
  125. {dostuff-0.2.12 → dostuff-0.2.14}/dostuff/tools/get_current_datetime.py +0 -0
  126. {dostuff-0.2.12 → dostuff-0.2.14}/dostuff/tools/mcp/get_mcp_tool_details.py +0 -0
  127. {dostuff-0.2.12 → dostuff-0.2.14}/dostuff/tools/mcp/search_mcp_tools.py +0 -0
  128. {dostuff-0.2.12 → dostuff-0.2.14}/dostuff/tools/memory/save_episode.py +0 -0
  129. {dostuff-0.2.12 → dostuff-0.2.14}/dostuff/tools/memory/save_memory.py +0 -0
  130. {dostuff-0.2.12 → dostuff-0.2.14}/dostuff/tools/names.py +0 -0
  131. {dostuff-0.2.12 → dostuff-0.2.14}/dostuff/tools/search/glob.py +0 -0
  132. {dostuff-0.2.12 → dostuff-0.2.14}/dostuff/tools/search/grep.py +0 -0
  133. {dostuff-0.2.12 → dostuff-0.2.14}/dostuff/tools/search/walk.py +0 -0
  134. {dostuff-0.2.12 → dostuff-0.2.14}/dostuff/tools/send_message.py +0 -0
  135. {dostuff-0.2.12 → dostuff-0.2.14}/dostuff/tools/settings.py +0 -0
  136. {dostuff-0.2.12 → dostuff-0.2.14}/dostuff/tools/stop_agent.py +0 -0
  137. {dostuff-0.2.12 → dostuff-0.2.14}/dostuff/tools/todo_write.py +0 -0
  138. {dostuff-0.2.12 → dostuff-0.2.14}/dostuff/tools/web_fetch.py +0 -0
  139. {dostuff-0.2.12 → dostuff-0.2.14}/dostuff/tools/web_search.py +0 -0
  140. {dostuff-0.2.12 → dostuff-0.2.14}/dostuff.egg-info/dependency_links.txt +0 -0
  141. {dostuff-0.2.12 → dostuff-0.2.14}/dostuff.egg-info/entry_points.txt +0 -0
  142. {dostuff-0.2.12 → dostuff-0.2.14}/dostuff.egg-info/top_level.txt +0 -0
  143. {dostuff-0.2.12 → dostuff-0.2.14}/setup.cfg +0 -0
  144. {dostuff-0.2.12 → dostuff-0.2.14}/tests/test_ask_user.py +0 -0
  145. {dostuff-0.2.12 → dostuff-0.2.14}/tests/test_bash_command.py +0 -0
  146. {dostuff-0.2.12 → dostuff-0.2.14}/tests/test_checkpoints_todos_caching.py +0 -0
  147. {dostuff-0.2.12 → dostuff-0.2.14}/tests/test_config_memory_mcp.py +0 -0
  148. {dostuff-0.2.12 → dostuff-0.2.14}/tests/test_create_agent_type.py +0 -0
  149. {dostuff-0.2.12 → dostuff-0.2.14}/tests/test_export_session.py +0 -0
  150. {dostuff-0.2.12 → dostuff-0.2.14}/tests/test_file_mentions.py +0 -0
  151. {dostuff-0.2.12 → dostuff-0.2.14}/tests/test_file_tools.py +0 -0
  152. {dostuff-0.2.12 → dostuff-0.2.14}/tests/test_jobs.py +0 -0
  153. {dostuff-0.2.12 → dostuff-0.2.14}/tests/test_mcp_e2e.py +0 -0
  154. {dostuff-0.2.12 → dostuff-0.2.14}/tests/test_mcp_env_references.py +0 -0
  155. {dostuff-0.2.12 → dostuff-0.2.14}/tests/test_mcp_oauth.py +0 -0
  156. {dostuff-0.2.12 → dostuff-0.2.14}/tests/test_opencode.py +0 -0
  157. {dostuff-0.2.12 → dostuff-0.2.14}/tests/test_optional_memory_and_instructions.py +0 -0
  158. {dostuff-0.2.12 → dostuff-0.2.14}/tests/test_pastes.py +0 -0
  159. {dostuff-0.2.12 → dostuff-0.2.14}/tests/test_permissions.py +0 -0
  160. {dostuff-0.2.12 → dostuff-0.2.14}/tests/test_roadmap_021.py +0 -0
  161. {dostuff-0.2.12 → dostuff-0.2.14}/tests/test_session_store.py +0 -0
  162. {dostuff-0.2.12 → dostuff-0.2.14}/tests/test_settings_tools.py +0 -0
  163. {dostuff-0.2.12 → dostuff-0.2.14}/tests/test_setup_wizard.py +0 -0
  164. {dostuff-0.2.12 → dostuff-0.2.14}/tests/test_side_question.py +0 -0
  165. {dostuff-0.2.12 → dostuff-0.2.14}/tests/test_side_question_litellm.py +0 -0
  166. {dostuff-0.2.12 → dostuff-0.2.14}/tests/test_skill_command.py +0 -0
  167. {dostuff-0.2.12 → dostuff-0.2.14}/tests/test_skills_discovery.py +0 -0
  168. {dostuff-0.2.12 → dostuff-0.2.14}/tests/test_slash_suggestion.py +0 -0
  169. {dostuff-0.2.12 → dostuff-0.2.14}/tests/test_steering.py +0 -0
  170. {dostuff-0.2.12 → dostuff-0.2.14}/tests/test_subagent.py +0 -0
  171. {dostuff-0.2.12 → dostuff-0.2.14}/tests/test_subagents_background.py +0 -0
  172. {dostuff-0.2.12 → dostuff-0.2.14}/tests/test_subagents_fork.py +0 -0
  173. {dostuff-0.2.12 → dostuff-0.2.14}/tests/test_subagents_run.py +0 -0
  174. {dostuff-0.2.12 → dostuff-0.2.14}/tests/test_subagents_store.py +0 -0
  175. {dostuff-0.2.12 → dostuff-0.2.14}/tests/test_subagents_types.py +0 -0
  176. {dostuff-0.2.12 → dostuff-0.2.14}/tests/test_terminal_signals.py +0 -0
  177. {dostuff-0.2.12 → dostuff-0.2.14}/tests/test_tool_schemas.py +0 -0
  178. {dostuff-0.2.12 → dostuff-0.2.14}/tests/test_turn_context.py +0 -0
  179. {dostuff-0.2.12 → dostuff-0.2.14}/tests/test_web_fetch.py +0 -0
  180. {dostuff-0.2.12 → dostuff-0.2.14}/tests/test_web_search.py +0 -0
  181. {dostuff-0.2.12 → dostuff-0.2.14}/tests/test_worktree.py +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: dostuff
3
- Version: 0.2.12
3
+ Version: 0.2.14
4
4
  Summary: DoStuff - a terminal coding agent for any LLM: TUI and headless mode, permissions, MCP, skills, web tools, sessions and git worktrees
5
5
  Author-email: Varun Kumawat <varunkumawatleap2@gmail.com>
6
6
  License-Expression: MIT
@@ -37,8 +37,15 @@ Provides-Extra: memory
37
37
  Requires-Dist: chromadb>=1.5.0; extra == "memory"
38
38
  Provides-Extra: search
39
39
  Requires-Dist: ddgs>=9.0; extra == "search"
40
+ Provides-Extra: images
41
+ Requires-Dist: Pillow>=10; extra == "images"
42
+ Provides-Extra: docs
43
+ Requires-Dist: pypdf>=4; extra == "docs"
44
+ Requires-Dist: python-docx>=1; extra == "docs"
45
+ Requires-Dist: openpyxl>=3.1; extra == "docs"
46
+ Requires-Dist: python-pptx>=0.6; extra == "docs"
40
47
  Provides-Extra: full
41
- Requires-Dist: dostuff[memory,search]; extra == "full"
48
+ Requires-Dist: dostuff[docs,images,memory,search]; extra == "full"
42
49
  Requires-Dist: onnxruntime>=1.16; extra == "full"
43
50
  Requires-Dist: grpcio>=1.52; extra == "full"
44
51
  Provides-Extra: dev
@@ -82,7 +89,7 @@ DoStuff is a terminal AI agent that runs anywhere `pip` runs. It gives you a ful
82
89
  - **MCP server support** — stdio (npx, uvx) and HTTP transports
83
90
  - **`@file` mentions** — type `@` in the prompt to pick a file or folder; its content (or listing) is sent with the message
84
91
  - **Project instructions** — `AGENTS.md` / `CLAUDE.md` from `~/.dostuff/`, the repo root and every folder down to the current one, combined
85
- - **Coding tools** — `read_file` (line numbers, offset/limit), `edit_file` (exact replacement), `multi_edit` (several replacements in one file, all or nothing), `write_file`, `grep`, `glob`, `list_files`, `delete_file`, `bash_command`, `web_fetch` (read a URL as text), `web_search` (free, no API key)
92
+ - **Coding tools** — `read_file` (line numbers, offset/limit; it also opens images and PDFs for a model that can view them, and Word / Excel / PowerPoint files as text), `edit_file` (exact replacement), `multi_edit` (several replacements in one file, all or nothing), `write_file`, `grep`, `glob`, `list_files`, `delete_file`, `bash_command`, `web_fetch` (read a URL as text), `web_search` (free, no API key)
86
93
  - **`ask_user`** — the agent asks you a real question — up to 4, with 2–4 options each, multi-select and a free-text "Other" — instead of guessing; the answers come back to it as one result and stay readable in `/resume`. See [Asking the user](#asking-the-user)
87
94
  - **`/btw` side questions** — ask about the conversation while a turn runs (or idle) without stopping or queuing it: one model call, no tools run, answered in a panel above the input and never added to the history; `f` hands the question to a background agent that can check it with tools. See [Side questions](#side-questions-btw)
88
95
  - **Mid-turn steering (`/steer`)** — send a correction to the turn that is running and the model reads it at the next tool boundary instead of waiting for the turn; plain messages steer by default, and `ui.mid_turn_messages: queue` batches them after the turn instead. See [Mid-turn steering](#mid-turn-steering-steer)
@@ -121,7 +128,9 @@ Optional features come as extras:
121
128
  | `pip install dostuff` | Everything except the extras below, including MCP (with OAuth tokens kept in the OS keyring) |
122
129
  | `pip install "dostuff[memory]"` | Long-term memory (facts and past decisions across sessions) and semantic MCP tool search, via ChromaDB. Large download |
123
130
  | `pip install "dostuff[search]"` | Steadier `web_search` through the `ddgs` package (several engines) instead of DuckDuckGo's HTML page |
124
- | `pip install "dostuff[full]"` | `memory` + `search` |
131
+ | `pip install "dostuff[docs]"` | Word, Excel and PowerPoint files (`.docx`, `.xlsx`, `.pptx`), and PDFs for models that can't read them, converted to text for `@path` and `read_file` (`pypdf`, `python-docx`, `openpyxl`, `python-pptx`) |
132
+ | `pip install "dostuff[images]"` | Pillow: large images are downscaled to fit the model's limit, and `Alt+V` reads the clipboard directly |
133
+ | `pip install "dostuff[full]"` | `memory` + `search` + `docs` + `images` |
125
134
  | `pip install "dostuff[dev]"` | `pytest` and `mypy`, for working on dostuff itself |
126
135
 
127
136
  Extras combine, e.g. `pip install "dostuff[memory,search]"`. Without `memory` everything else
@@ -226,9 +235,10 @@ In the TUI:
226
235
  | `!<command>` | Run a shell command directly (no approval); the command and its output are shown to the model on the next turn |
227
236
  | `# <note>` | Add `- <note>` to `AGENTS.md`: you pick this project's or the global one (`~/.dostuff/AGENTS.md`); the agent follows it from the next message |
228
237
  | `Shift+Enter` | Insert a newline (multi-line input). If your terminal sends it as plain Enter, use `\` then `Enter`, `Ctrl+Enter`, `Alt+Enter` or `Ctrl+J` |
229
- | `@path` | Attach a file (numbered lines) or a folder listing to the message. Typing `@` lists matching project paths: `Tab` / `Enter` completes, a folder opens for the next part. `@"a b.txt"` for spaces. Also works with `dostuff -p`. `.env` files and binaries are never attached |
238
+ | `@path` | Attach a file (numbered lines) or a folder listing to the message. Typing `@` lists matching project paths: `Tab` / `Enter` completes, a folder opens for the next part. `@"a b.txt"` for spaces. Also works with `dostuff -p`. `.env` files and binaries are never attached. An image (PNG, JPEG, GIF or WebP, told apart by its content, not its extension) is sent to the model as an image when the model can read images, and shows as `[Image #1 · shot.png · 1280×720]`; on a model that can't, or over 3.75 MB, or more than 20 in one message, nothing is sent and your prompt goes back in the input (`-p` exits with code 1). With `dostuff[images]`, an image wider or taller than 1568 px, or over 3.75 MB, is downscaled first (a GIF only when it is over 3.75 MB). A PDF goes to the model as a document when the model reads PDFs (up to 32 MB and 100 pages), shown as `[PDF · report.pdf · 12 pages]`; otherwise its text is attached. Word, Excel and PowerPoint files (`.docx`, `.xlsx`, `.pptx`) are attached as text: headings and tables as markdown, one table per sheet (values, not formulas), one section per slide with its notes. A converted file over 200 lines (`loop.paste_file_lines`) is saved to `.dostuff/attachments/` and the model reads it from there. Converting needs `dostuff[docs]`; without it, or for the old `.doc` / `.xls` / `.ppt` formats, the prompt goes back with the reason. Images and PDFs are copied to `.dostuff/attachments/` and removed after `loop.attachment_retention_days` (30). For a model dostuff can't tell about, set `vision: true` / `pdf_input: true` (or `false`) on its `models:` entry |
230
239
  | `Tab` | While typing a slash command, accept the dim ghost text after the cursor: the rest of the command name, then its flag (`/model ` → `--active`, `/fork ` → `--worktree`). `Right` accepts it too |
231
- | Paste | A paste over 10 lines (`ui.paste_collapse_lines`) or 2,000 chars shows as `[Pasted text #1 +243 lines]` and is expanded when you send it. Over 200 lines (`loop.paste_file_lines`) it's saved to `.dostuff/pastes/` and the model reads it from there, so it doesn't fill the context; files are removed after `loop.paste_retention_days` (7) |
240
+ | Paste | A paste over 10 lines (`ui.paste_collapse_lines`) or 2,000 chars shows as `[Pasted text #1 +243 lines]` and is expanded when you send it. Over 200 lines (`loop.paste_file_lines`) it's saved to `.dostuff/pastes/` and the model reads it from there, so it doesn't fill the context; files are removed after `loop.paste_retention_days` (7). Dragging an image or document into the terminal pastes its path; dostuff turns it into an `@path` mention, or, for an image outside the project, attaches it like `Alt+V` |
241
+ | `Alt+V` | Paste an image from the clipboard (a screenshot, an image copied in a browser). It shows as `[Image #1]` in the input, and is sent with your message under the same rules as an `@image` mention (a model that can read images, 3.75 MB, 20 per message). `Ctrl+V` stays the terminal's own paste, which carries only text. Uses Pillow when installed (`dostuff[images]`), otherwise PowerShell on Windows, `osascript` on macOS, and `wl-paste` or `xclip` on Linux. Checked on Windows; macOS and Linux are untested so far |
232
242
  | `Up` / `Down` | On the first / last line of the input: previous / next prompt typed in this directory (saved in `~/.dostuff/data/prompt_history.jsonl`) |
233
243
  | `Ctrl+R` | Search the prompts typed in this directory (type to filter, `Enter` puts the prompt in the input) |
234
244
  | `Esc` `Esc` | With an empty input: take back your last prompt. It and everything after it (answer, tool calls) leave the conversation and the prompt goes back in the input to edit and resend. Files that turn changed stay as they are; `/undo` restores them |
@@ -846,7 +856,7 @@ worktree), with no terminal. stdin is one JSON object:
846
856
  | Event | Extra keys |
847
857
  |---|---|
848
858
  | `PreToolUse`, `PostToolUse` | `tool_name`, `tool_input`, `tool_use_id`; `PostToolUse` also `tool_response` (the result, already truncated) |
849
- | `UserPromptSubmit` | `prompt` |
859
+ | `UserPromptSubmit` | `prompt` (the text you typed; images and documents appear as `[Image: name]` / `[PDF: name]`), `attachments` (`[{"name", "kind", "path"}]`, empty when there are none) |
850
860
  | `SessionStart` | `source` |
851
861
  | `Stop`, `SubagentStop` | `last_assistant_message`, `stop_hook_active` (true once a Stop hook already continued this turn) |
852
862
  | `SubagentStart` | `agent_id`, `agent_type`, `background`, `prompt` |
@@ -34,7 +34,7 @@ DoStuff is a terminal AI agent that runs anywhere `pip` runs. It gives you a ful
34
34
  - **MCP server support** — stdio (npx, uvx) and HTTP transports
35
35
  - **`@file` mentions** — type `@` in the prompt to pick a file or folder; its content (or listing) is sent with the message
36
36
  - **Project instructions** — `AGENTS.md` / `CLAUDE.md` from `~/.dostuff/`, the repo root and every folder down to the current one, combined
37
- - **Coding tools** — `read_file` (line numbers, offset/limit), `edit_file` (exact replacement), `multi_edit` (several replacements in one file, all or nothing), `write_file`, `grep`, `glob`, `list_files`, `delete_file`, `bash_command`, `web_fetch` (read a URL as text), `web_search` (free, no API key)
37
+ - **Coding tools** — `read_file` (line numbers, offset/limit; it also opens images and PDFs for a model that can view them, and Word / Excel / PowerPoint files as text), `edit_file` (exact replacement), `multi_edit` (several replacements in one file, all or nothing), `write_file`, `grep`, `glob`, `list_files`, `delete_file`, `bash_command`, `web_fetch` (read a URL as text), `web_search` (free, no API key)
38
38
  - **`ask_user`** — the agent asks you a real question — up to 4, with 2–4 options each, multi-select and a free-text "Other" — instead of guessing; the answers come back to it as one result and stay readable in `/resume`. See [Asking the user](#asking-the-user)
39
39
  - **`/btw` side questions** — ask about the conversation while a turn runs (or idle) without stopping or queuing it: one model call, no tools run, answered in a panel above the input and never added to the history; `f` hands the question to a background agent that can check it with tools. See [Side questions](#side-questions-btw)
40
40
  - **Mid-turn steering (`/steer`)** — send a correction to the turn that is running and the model reads it at the next tool boundary instead of waiting for the turn; plain messages steer by default, and `ui.mid_turn_messages: queue` batches them after the turn instead. See [Mid-turn steering](#mid-turn-steering-steer)
@@ -73,7 +73,9 @@ Optional features come as extras:
73
73
  | `pip install dostuff` | Everything except the extras below, including MCP (with OAuth tokens kept in the OS keyring) |
74
74
  | `pip install "dostuff[memory]"` | Long-term memory (facts and past decisions across sessions) and semantic MCP tool search, via ChromaDB. Large download |
75
75
  | `pip install "dostuff[search]"` | Steadier `web_search` through the `ddgs` package (several engines) instead of DuckDuckGo's HTML page |
76
- | `pip install "dostuff[full]"` | `memory` + `search` |
76
+ | `pip install "dostuff[docs]"` | Word, Excel and PowerPoint files (`.docx`, `.xlsx`, `.pptx`), and PDFs for models that can't read them, converted to text for `@path` and `read_file` (`pypdf`, `python-docx`, `openpyxl`, `python-pptx`) |
77
+ | `pip install "dostuff[images]"` | Pillow: large images are downscaled to fit the model's limit, and `Alt+V` reads the clipboard directly |
78
+ | `pip install "dostuff[full]"` | `memory` + `search` + `docs` + `images` |
77
79
  | `pip install "dostuff[dev]"` | `pytest` and `mypy`, for working on dostuff itself |
78
80
 
79
81
  Extras combine, e.g. `pip install "dostuff[memory,search]"`. Without `memory` everything else
@@ -178,9 +180,10 @@ In the TUI:
178
180
  | `!<command>` | Run a shell command directly (no approval); the command and its output are shown to the model on the next turn |
179
181
  | `# <note>` | Add `- <note>` to `AGENTS.md`: you pick this project's or the global one (`~/.dostuff/AGENTS.md`); the agent follows it from the next message |
180
182
  | `Shift+Enter` | Insert a newline (multi-line input). If your terminal sends it as plain Enter, use `\` then `Enter`, `Ctrl+Enter`, `Alt+Enter` or `Ctrl+J` |
181
- | `@path` | Attach a file (numbered lines) or a folder listing to the message. Typing `@` lists matching project paths: `Tab` / `Enter` completes, a folder opens for the next part. `@"a b.txt"` for spaces. Also works with `dostuff -p`. `.env` files and binaries are never attached |
183
+ | `@path` | Attach a file (numbered lines) or a folder listing to the message. Typing `@` lists matching project paths: `Tab` / `Enter` completes, a folder opens for the next part. `@"a b.txt"` for spaces. Also works with `dostuff -p`. `.env` files and binaries are never attached. An image (PNG, JPEG, GIF or WebP, told apart by its content, not its extension) is sent to the model as an image when the model can read images, and shows as `[Image #1 · shot.png · 1280×720]`; on a model that can't, or over 3.75 MB, or more than 20 in one message, nothing is sent and your prompt goes back in the input (`-p` exits with code 1). With `dostuff[images]`, an image wider or taller than 1568 px, or over 3.75 MB, is downscaled first (a GIF only when it is over 3.75 MB). A PDF goes to the model as a document when the model reads PDFs (up to 32 MB and 100 pages), shown as `[PDF · report.pdf · 12 pages]`; otherwise its text is attached. Word, Excel and PowerPoint files (`.docx`, `.xlsx`, `.pptx`) are attached as text: headings and tables as markdown, one table per sheet (values, not formulas), one section per slide with its notes. A converted file over 200 lines (`loop.paste_file_lines`) is saved to `.dostuff/attachments/` and the model reads it from there. Converting needs `dostuff[docs]`; without it, or for the old `.doc` / `.xls` / `.ppt` formats, the prompt goes back with the reason. Images and PDFs are copied to `.dostuff/attachments/` and removed after `loop.attachment_retention_days` (30). For a model dostuff can't tell about, set `vision: true` / `pdf_input: true` (or `false`) on its `models:` entry |
182
184
  | `Tab` | While typing a slash command, accept the dim ghost text after the cursor: the rest of the command name, then its flag (`/model ` → `--active`, `/fork ` → `--worktree`). `Right` accepts it too |
183
- | Paste | A paste over 10 lines (`ui.paste_collapse_lines`) or 2,000 chars shows as `[Pasted text #1 +243 lines]` and is expanded when you send it. Over 200 lines (`loop.paste_file_lines`) it's saved to `.dostuff/pastes/` and the model reads it from there, so it doesn't fill the context; files are removed after `loop.paste_retention_days` (7) |
185
+ | Paste | A paste over 10 lines (`ui.paste_collapse_lines`) or 2,000 chars shows as `[Pasted text #1 +243 lines]` and is expanded when you send it. Over 200 lines (`loop.paste_file_lines`) it's saved to `.dostuff/pastes/` and the model reads it from there, so it doesn't fill the context; files are removed after `loop.paste_retention_days` (7). Dragging an image or document into the terminal pastes its path; dostuff turns it into an `@path` mention, or, for an image outside the project, attaches it like `Alt+V` |
186
+ | `Alt+V` | Paste an image from the clipboard (a screenshot, an image copied in a browser). It shows as `[Image #1]` in the input, and is sent with your message under the same rules as an `@image` mention (a model that can read images, 3.75 MB, 20 per message). `Ctrl+V` stays the terminal's own paste, which carries only text. Uses Pillow when installed (`dostuff[images]`), otherwise PowerShell on Windows, `osascript` on macOS, and `wl-paste` or `xclip` on Linux. Checked on Windows; macOS and Linux are untested so far |
184
187
  | `Up` / `Down` | On the first / last line of the input: previous / next prompt typed in this directory (saved in `~/.dostuff/data/prompt_history.jsonl`) |
185
188
  | `Ctrl+R` | Search the prompts typed in this directory (type to filter, `Enter` puts the prompt in the input) |
186
189
  | `Esc` `Esc` | With an empty input: take back your last prompt. It and everything after it (answer, tool calls) leave the conversation and the prompt goes back in the input to edit and resend. Files that turn changed stay as they are; `/undo` restores them |
@@ -798,7 +801,7 @@ worktree), with no terminal. stdin is one JSON object:
798
801
  | Event | Extra keys |
799
802
  |---|---|
800
803
  | `PreToolUse`, `PostToolUse` | `tool_name`, `tool_input`, `tool_use_id`; `PostToolUse` also `tool_response` (the result, already truncated) |
801
- | `UserPromptSubmit` | `prompt` |
804
+ | `UserPromptSubmit` | `prompt` (the text you typed; images and documents appear as `[Image: name]` / `[PDF: name]`), `attachments` (`[{"name", "kind", "path"}]`, empty when there are none) |
802
805
  | `SessionStart` | `source` |
803
806
  | `Stop`, `SubagentStop` | `last_assistant_message`, `stop_hook_active` (true once a Stop hook already continued this turn) |
804
807
  | `SubagentStart` | `agent_id`, `agent_type`, `background`, `prompt` |
@@ -2,12 +2,26 @@ from typing import Any
2
2
 
3
3
  import litellm
4
4
  from litellm import acompletion
5
+ from dostuff.helpers.agent.attachments import content_text, hydrate
5
6
  from dostuff.tools.definitions import TOOL_SCHEMAS, default_tool_names
6
7
  from dostuff.lib.model import completion_kwargs, uses_explicit_prompt_caching
7
8
  from dostuff.lib.tracing import content_attr, tracer
8
9
  from opentelemetry.trace import Status, StatusCode
9
10
 
10
11
 
12
+ # Names of attachments whose stored file was gone when a request was built (REQ-1.3); the loop reports each once
13
+ unavailable_attachments: list[str] = []
14
+ _reported_unavailable: set[str] = set()
15
+
16
+
17
+ def take_unavailable_attachments() -> list[str]:
18
+ """Missing attachments not reported yet in this process (every later request still sends the stand-in)."""
19
+ names = [n for n in dict.fromkeys(unavailable_attachments) if n not in _reported_unavailable]
20
+ unavailable_attachments.clear()
21
+ _reported_unavailable.update(names)
22
+ return names
23
+
24
+
11
25
  # Two breakpoints: the system prompt (tools + instructions, stable across turns) and the last
12
26
  # message, which moves each call, so the next call reads everything before it from the cache.
13
27
  CACHE_BREAKPOINTS: list[dict[str, Any]] = [
@@ -73,7 +87,9 @@ async def call_agent(steps_history: list, system_instruction: str, tool_names: l
73
87
  if tool_names is None:
74
88
  tool_names = default_tool_names()
75
89
  active_schemas = [TOOL_SCHEMAS[name] for name in tool_names if name in TOOL_SCHEMAS]
76
- messages = [{"role": "system", "content": system_instruction}] + provider_messages(steps_history)
90
+ # History holds attachment refs; only the request carries their bytes (CON-004)
91
+ messages = [{"role": "system", "content": system_instruction}] + hydrate(provider_messages(steps_history),
92
+ missing=unavailable_attachments)
77
93
  request = build_request_kwargs(stream)
78
94
 
79
95
  span = tracer.start_span("model_call")
@@ -82,7 +98,7 @@ async def call_agent(steps_history: list, system_instruction: str, tool_names: l
82
98
  last_msg = steps_history[-1] if steps_history else None
83
99
  if last_msg:
84
100
  span.set_attribute("model.input.last_message_role", last_msg.get("role", ""))
85
- span.set_attribute("model.input.last_message", content_attr(last_msg.get("content") or last_msg.get("tool_calls") or ""))
101
+ span.set_attribute("model.input.last_message", content_attr(content_text(last_msg.get("content")) or last_msg.get("tool_calls") or ""))
86
102
  span.set_attribute("model.input.step_count", len(steps_history))
87
103
 
88
104
  try:
@@ -6,13 +6,15 @@ from dostuff.lib.mcp.mcp_client import MCPClient
6
6
  from dostuff.lib.tracing import content_attr, tracer
7
7
  from dostuff.helpers.agent.constants import MAX_ITERATIONS
8
8
  from dostuff.helpers.agent.manage_context import compact_context
9
- from dostuff.agent.call_agent import call_agent
9
+ from dostuff.agent.call_agent import call_agent, take_unavailable_attachments
10
10
  from opentelemetry.trace import Status, StatusCode
11
11
  from dostuff.helpers.agent.append_step import append_step
12
+ from dostuff.helpers.agent.attachments import ref_chips
13
+ from dostuff.helpers.agent.tool_attachments import collecting, tool_attachment_step
12
14
  import asyncio
13
15
  import inspect
14
16
  import random
15
- from dataclasses import dataclass
17
+ from dataclasses import dataclass, field
16
18
  from dostuff.agent.permissions import PLAN_MODE_INSTRUCTION, PLAN_MODE_OFF_INSTRUCTION, SessionPermissions
17
19
  from dostuff.agent.run_tool import (
18
20
  CANCELLED_RESULT, authorize_batch, authorize_tool, dispatch_tool, post_tool_use, pre_tool_use,
@@ -106,6 +108,8 @@ class _ToolCall:
106
108
  error: str | None = None # set when the call can't run (bad JSON, unavailable tool, denied)
107
109
  result: str | None = None
108
110
  hook: HookOutcome | None = None # its PreToolUse outcome, an input to the permission check
111
+ # Images / PDFs the call opened (read_file, MCP), sent in one user step after the tool results (multimodal D8)
112
+ attachments: list[dict[str, Any]] = field(default_factory=list)
109
113
 
110
114
 
111
115
  def _parse_tool_calls(tool_calls: list[Any], tool_names: list[str] | None) -> list[_ToolCall]:
@@ -250,9 +254,9 @@ async def loop(session_id: str, turn_id: str, user_text: str, dynamic_system_ins
250
254
  turn_type=turn_type, adapter=adapter)
251
255
  return True
252
256
 
253
- async def append_note(text: str) -> None:
257
+ async def append_note(text: str | list[dict[str, Any]]) -> None:
254
258
  """A harness-authored user step: a Stop-hook continuation, background notices, a send_message or a
255
- framed steering message."""
259
+ framed steering message (text, then its image refs)."""
256
260
  await append_step({"role": "user", "content": text}, steps_history, working_history, current_session_history, session_id, store, turn_type)
257
261
 
258
262
  async def sync_plan_mode() -> None:
@@ -280,8 +284,11 @@ async def loop(session_id: str, turn_id: str, user_text: str, dynamic_system_ins
280
284
  continue
281
285
  if steer_msg.content is None:
282
286
  continue # unreachable: take_ready only returns ready or failed entries
287
+ prompt: str | list[dict[str, Any]] = steer_msg.content
288
+ if steer_msg.parts:
289
+ prompt = [{"type": "text", "text": steer_msg.content}, *steer_msg.parts]
283
290
  blocked, context = await user_prompt_submit(
284
- steer_msg.content, session_id=session_id, turn_id=turn_id, turn_type=turn_type,
291
+ prompt, session_id=session_id, turn_id=turn_id, turn_type=turn_type,
285
292
  adapter=adapter)
286
293
  if blocked is not None:
287
294
  await loop_emit("steer_blocked", {"id": steer_msg.id, "reason": blocked},
@@ -291,7 +298,9 @@ async def loop(session_id: str, turn_id: str, user_text: str, dynamic_system_ins
291
298
  # In-band note, not a system fold: a mid-turn system change would invalidate the
292
299
  # provider's whole cached prefix — the system prompt stays byte-stable in a turn.
293
300
  await append_note(f"{PROMPT_CONTEXT_HEADER}\n{context}")
294
- await append_note(frame_steered(steer_msg.content)) # the steer message's only write (CON-004), framed (D6)
301
+ framed = frame_steered(steer_msg.content)
302
+ # the steer message's only write (CON-004), framed (D6); images after the text, as in a prompt
303
+ await append_note([{"type": "text", "text": framed}, *steer_msg.parts] if steer_msg.parts else framed)
295
304
  await loop_emit("steered", {"id": steer_msg.id, "index": len(steps_history) - 1},
296
305
  adapter=adapter)
297
306
  delivered += 1
@@ -373,6 +382,9 @@ async def loop(session_id: str, turn_id: str, user_text: str, dynamic_system_ins
373
382
  tool_names=tool_names,
374
383
  stream=stream,
375
384
  )
385
+ for name in take_unavailable_attachments(): # resumed after a sweep (multimodal REQ-1.3)
386
+ await loop_emit("error", f"Attachment unavailable: {name} (no longer in "
387
+ ".dostuff/attachments/)", adapter=adapter)
376
388
  if hasattr(interaction, "__aiter__"):
377
389
  interaction = await _consume_stream(interaction, adapter, loop_emit, progress)
378
390
  break
@@ -563,10 +575,16 @@ async def loop(session_id: str, turn_id: str, user_text: str, dynamic_system_ins
563
575
  cancelled = True
564
576
  break
565
577
 
578
+ async def dispatch_collecting(call: _ToolCall, fork: ForkContext | None) -> Any:
579
+ # Its own collector: in this task's context, so parallel calls don't mix their images (D8)
580
+ with collecting() as found:
581
+ call.attachments = found
582
+ return await dispatch_tool(call.name, dict(call.args), mcp_client=mcp_client, session_id=session_id, turn_id=turn_id, adapter=adapter, permissions=permissions, owner=owner, fork_context=fork)
583
+
566
584
  def start(call: _ToolCall) -> asyncio.Task:
567
585
  fork = fork_context() if call.name in _FORK_TOOLS else None
568
586
  return asyncio.ensure_future(asyncio.wait_for(
569
- dispatch_tool(call.name, dict(call.args), mcp_client=mcp_client, session_id=session_id, turn_id=turn_id, adapter=adapter, permissions=permissions, owner=owner, fork_context=fork),
587
+ dispatch_collecting(call, fork),
570
588
  timeout=None if call.name in _UNTIMED_TOOLS else TOOL_TIMEOUT_S,
571
589
  ))
572
590
 
@@ -576,8 +594,11 @@ async def loop(session_id: str, turn_id: str, user_text: str, dynamic_system_ins
576
594
  for call, task in zip(batch, tasks):
577
595
  if task.cancelled():
578
596
  call.result = CANCELLED_RUNNING_RESULT if _is_thread_tool(call.name) else CANCELLED_RESULT
597
+ call.attachments = []
579
598
  continue
580
599
  exc = task.exception()
600
+ if exc is not None:
601
+ call.attachments = []
581
602
  if isinstance(exc, asyncio.TimeoutError):
582
603
  call.result = f"Error: tool '{call.name}' timed out after {TOOL_TIMEOUT_S:.0f}s."
583
604
  elif exc is not None:
@@ -619,6 +640,11 @@ async def loop(session_id: str, turn_id: str, user_text: str, dynamic_system_ins
619
640
  "content": truncate_tool_output(result_text, max_tool_output_chars),
620
641
  }
621
642
  await append_step(result_step, steps_history, working_history, current_session_history, session_id, store, turn_type)
643
+ attached = [ref for call in calls for ref in call.attachments]
644
+ if attached: # after every tool step, so the provider sees tool results, then the images (D8)
645
+ attachment_step = tool_attachment_step(attached)
646
+ await append_step(attachment_step, steps_history, working_history, current_session_history, session_id, store, turn_type)
647
+ await loop_emit("system", ref_chips(attachment_step["content"]), adapter=adapter)
622
648
  iter_span.set_status(Status(StatusCode.OK))
623
649
 
624
650
  if cancelled or is_cancelled(adapter):
@@ -1,12 +1,14 @@
1
1
  """One subagent run: its loop, the partial report when it stops early, and the worktree close-out (spec D1)."""
2
- from typing import Any, Literal
2
+ from typing import TYPE_CHECKING, Any, Literal
3
3
 
4
4
  from dostuff.agent.subagents import RESTRICTED_SUBAGENT_TOOLS
5
5
  from dostuff.agent.subagents.adapter import SubagentAdapter
6
6
  from dostuff.helpers.tools.project_root import project_root
7
- from dostuff.lib.mcp.mcp_client import MCPClient
8
7
  from dostuff.lib.worktree import Worktree, WorktreeError, remove_worktree, worktree_changes
9
8
 
9
+ if TYPE_CHECKING: # the TUI imports this module before its first frame; the MCP SDK takes seconds
10
+ from dostuff.lib.mcp.mcp_client import MCPClient
11
+
10
12
  WRAP_UP_PROMPT = (
11
13
  "You have run out of steps. Do not call any more tools. Report what you found so far, "
12
14
  "what is still unknown, and what the next steps would be."
@@ -100,7 +102,7 @@ def resolve_subagent_tools(requested_tools: list[str] | None) -> tuple[list[str]
100
102
 
101
103
  async def run_agent_loop(
102
104
  task: str,
103
- mcp_client: MCPClient | None,
105
+ mcp_client: "MCPClient | None",
104
106
  session_id: str,
105
107
  turn_id: str,
106
108
  adapter: SubagentAdapter,
@@ -52,11 +52,15 @@ from dostuff.lib.model import get_model
52
52
  from dostuff.lib.tracing import session_id_var, turn_id_var
53
53
  from dostuff.helpers.agent.append_step import append_step
54
54
  from dostuff.helpers.agent.loop_check_cancelled import CANCELLED_TURN
55
+ from dostuff.helpers.agent import clipboard
56
+ from dostuff.helpers.agent.attachments import classify_attachment, delete_attachments, ref_chips, sweep_old_attachments
57
+ from dostuff.helpers.agent.tool_attachments import is_tool_attachment_step
55
58
  from dostuff.helpers.agent.file_mentions import (PARTIAL_MENTION_RE, attached_paths, expand_file_mentions,
56
59
  format_mention, mention_candidates, strip_attachments)
57
60
  from dostuff.helpers.agent.model_cost import format_cost
58
61
  from dostuff.helpers.agent.notices import WAKE_LIMIT, agent_notice_line, fmt_agent_runtime, format_notices, get_notice_queue, parse_notices
59
62
  from dostuff.helpers.agent.pastes import PasteStore, sweep_old_pastes
63
+ from dostuff.helpers.tools.resolve_safe_path import is_denied_for_read
60
64
  from dostuff.helpers.agent.steering import SteerMessage, SteeringQueue, unframe_steered
61
65
  from dostuff.helpers.agent.side_question import (
62
66
  BTW_FORK_DESCRIPTION, BTW_FORK_PROMPT, add_exchange, answer_side_question, discard_snapshot, kept_prompt,
@@ -1196,6 +1200,7 @@ class EnterSubmits(TextArea):
1196
1200
  self._draft = ""
1197
1201
  self.recalled_text: str | None = None # last text put in by recall (keeps the "/" menu shut)
1198
1202
  self.pastes = PasteStore()
1203
+ self.images = clipboard.PastedImages() # alt+v and dropped images; the app shares its own
1199
1204
  self.paste_collapse_lines = 0 # set by the app from ui.paste_collapse_lines
1200
1205
  self.commands: Iterable[str] = COMMAND_DESCRIPTIONS # for ghost text; the app adds the skill commands
1201
1206
  self.skills: Iterable[str] = () # "/name" of each skill, for mentions; the app fills it in
@@ -1300,16 +1305,43 @@ class EnterSubmits(TextArea):
1300
1305
  self.move_cursor((row, start + len(command) + 1))
1301
1306
 
1302
1307
  async def _on_paste(self, event: Paste) -> None:
1303
- """A long paste goes in as `[Pasted text #N +L lines]`; the app swaps the text back on submit."""
1308
+ """A long paste goes in as `[Pasted text #N +L lines]`; the app swaps the text back on submit. A paste that
1309
+ is just the path of an image or document (a file dragged into the terminal) goes in as its mention."""
1304
1310
  text = event.text.replace("\r\n", "\n").replace("\r", "\n")
1305
- if self.read_only or not self.pastes.should_collapse(text, self.paste_collapse_lines):
1311
+ if self.read_only:
1306
1312
  return # Textual runs TextArea._on_paste next (handlers go down the MRO), which inserts it
1313
+ dropped = clipboard.dropped_path_text(text)
1314
+ replacement = await asyncio.to_thread(self._dropped_file, dropped) if dropped else None
1315
+ if replacement is None:
1316
+ if not self.pastes.should_collapse(text, self.paste_collapse_lines):
1317
+ return
1318
+ replacement = self.pastes.add(text)
1307
1319
  event.stop()
1308
1320
  event.prevent_default()
1309
- if result := self._replace_via_keyboard(self.pastes.add(text), *self.selection):
1321
+ self.insert_at_cursor(replacement)
1322
+
1323
+ def insert_at_cursor(self, text: str) -> None:
1324
+ """`text` in place of the selection, as typing would put it (undo works)."""
1325
+ if result := self._replace_via_keyboard(text, *self.selection):
1310
1326
  self.move_cursor(result.end_location)
1311
1327
  self.focus()
1312
1328
 
1329
+ def _dropped_file(self, raw: str) -> str | None:
1330
+ """What a dropped file goes in as (multimodal REQ-3.3): `@path ` inside the project, so the mention handles
1331
+ it on submit; an image outside it is read now and goes in as `[Image #N]`, like alt+v (a mention can't
1332
+ reach outside the project). None: not an existing image or document, so the paste stays text."""
1333
+ try:
1334
+ path = Path(raw).expanduser().resolve()
1335
+ kind = classify_attachment(path) if path.is_file() else None
1336
+ if kind is None or is_denied_for_read(path):
1337
+ return None
1338
+ try:
1339
+ return format_mention(path.relative_to(Path.cwd().resolve()).as_posix()) + " "
1340
+ except ValueError:
1341
+ return self.images.add(path.read_bytes()) if kind == "image" else None
1342
+ except (OSError, ValueError):
1343
+ return None
1344
+
1313
1345
  def _menu(self) -> CommandMenu | None:
1314
1346
  try:
1315
1347
  menu = self.app.query_one("#command-menu", CommandMenu)
@@ -1423,7 +1455,8 @@ class SettingsEditor(TextArea):
1423
1455
 
1424
1456
 
1425
1457
  def _agent_registry() -> Any:
1426
- """The subagent registry, imported late: it pulls in the MCP client, which loads after the first frame."""
1458
+ """The subagent registry, imported late. This runs before the first frame (the status bar reads it),
1459
+ so nothing it imports at module level may load the MCP SDK or litellm."""
1427
1460
  from dostuff.agent.subagents.registry import get_agent_registry
1428
1461
  return get_agent_registry()
1429
1462
 
@@ -1892,6 +1925,7 @@ class DostuffTUI(App):
1892
1925
  Binding("ctrl+o", "toggle_tool_results", "Expand tool output", priority=True),
1893
1926
  Binding("shift+tab", "cycle_permission_mode", "Cycle permission mode", priority=True),
1894
1927
  Binding("ctrl+r", "history_search", "Search prompt history", priority=True),
1928
+ Binding("alt+v", "paste_image", "Paste an image from the clipboard"),
1895
1929
  Binding("ctrl+b", "background_jobs", "Move running commands to the background", priority=True),
1896
1930
  ]
1897
1931
 
@@ -1982,6 +2016,7 @@ class DostuffTUI(App):
1982
2016
  self._tool_results_expanded = False # Ctrl+O; new results follow it
1983
2017
  self._history_path = self.config.get_data_dir() / "prompt_history.jsonl"
1984
2018
  self._pastes = PasteStore() # collapsed pastes in the input (helpers/agent/pastes.py)
2019
+ self._images = clipboard.PastedImages() # alt+v images in the input, `[Image #N]` (multimodal REQ-3)
1985
2020
  self.worktree: Worktree | None = None # set while the cwd is a dostuff git worktree
1986
2021
  self.exit_note = "" # printed by cli.py after the TUI closes (e.g. a kept worktree)
1987
2022
  self._notify_kind = self.config.notifications # /notifications changes it for the session
@@ -2141,9 +2176,11 @@ class DostuffTUI(App):
2141
2176
  _agent_registry().attach_store(self.store) # agent rows and transcripts (subagents D14)
2142
2177
  inp.prompt_history = load_history(self._history_path, os.getcwd())
2143
2178
  inp.pastes = self._pastes
2179
+ inp.images = self._images
2144
2180
  inp.paste_collapse_lines = self.config.paste_collapse_lines
2145
2181
  try:
2146
2182
  await asyncio.to_thread(sweep_old_pastes, self.config.paste_retention_days)
2183
+ await asyncio.to_thread(sweep_old_attachments, self.config.attachment_retention_days)
2147
2184
  except OSError:
2148
2185
  pass
2149
2186
 
@@ -2381,6 +2418,16 @@ class DostuffTUI(App):
2381
2418
  self._append_call_result(f"{prefix}{step.get('name', '')}: {content}")
2382
2419
  return
2383
2420
  if role == "user":
2421
+ if is_tool_attachment_step(step): # what read_file / an MCP tool opened: the chips the live view showed
2422
+ self._append(prefix + ref_chips(content), msg_type="system")
2423
+ return
2424
+ if isinstance(content, list): # a prompt with images or PDFs: its text, then a chip per attachment
2425
+ self._append(prefix + strip_attachments(content), msg_type="user")
2426
+ attached = attached_paths(content)
2427
+ if attached:
2428
+ self._append("Attached " + ", ".join(attached), msg_type="system")
2429
+ self._append(ref_chips(content), msg_type="system")
2430
+ return
2384
2431
  shell = _parse_shell_step(content)
2385
2432
  stop_note = parse_stop_note(content)
2386
2433
  notices = parse_notices(content)
@@ -3668,6 +3715,7 @@ class DostuffTUI(App):
3668
3715
  "Shift+Tab cycle permission mode (ask → auto → plan → allowlist) · "
3669
3716
  "Ctrl+Backspace / Ctrl+W delete word · Ctrl+Delete delete next word · "
3670
3717
  "Ctrl+O expand/collapse tool output (or click one) · Ctrl+R search prompt history · "
3718
+ "Alt+V paste an image from the clipboard · "
3671
3719
  "Esc Esc (empty input) edit the previous prompt · / command menu",
3672
3720
  msg_type="system",
3673
3721
  )
@@ -3744,11 +3792,16 @@ class DostuffTUI(App):
3744
3792
  the entry to the loop. The "Attached …" lines show here, as they do for a prompt."""
3745
3793
  try:
3746
3794
  mentions = skill_mentions(msg.raw, self._skill_commands) # what was typed, before anything expands
3747
- expansion = await asyncio.to_thread(expand_file_mentions, msg.raw, self.config.max_tool_output_chars)
3795
+ expansion = await asyncio.to_thread(expand_file_mentions, msg.raw, self.config.max_tool_output_chars,
3796
+ images=self._images, file_lines=self.config.paste_file_lines)
3748
3797
  if expansion.attached:
3749
3798
  self._append("Attached " + ", ".join(expansion.attached), msg_type="system")
3750
3799
  if expansion.skipped:
3751
3800
  self._append("Not attached: " + "; ".join(expansion.skipped), msg_type="error")
3801
+ if expansion.refused: # an image that can't be sent: reported, never delivered (multimodal CON-006)
3802
+ self._steering.fail(msg.id, "Not attached: " + "; ".join(expansion.refused))
3803
+ self._render_queue()
3804
+ return
3752
3805
  content = await asyncio.to_thread(self._pastes.resolve, expansion.content, self.session_id,
3753
3806
  self.config.paste_file_lines, self.config.max_tool_output_chars)
3754
3807
  content = with_mention_note(content, mentions)
@@ -3758,7 +3811,7 @@ class DostuffTUI(App):
3758
3811
  self._steering.fail(msg.id, str(e))
3759
3812
  self._render_queue()
3760
3813
  return
3761
- self._steering.ready(msg.id, content)
3814
+ self._steering.ready(msg.id, content, expansion.parts)
3762
3815
  self._render_queue()
3763
3816
 
3764
3817
  # ── Approval prompt ────────────────────────────────────────────────────────
@@ -4212,17 +4265,23 @@ class DostuffTUI(App):
4212
4265
  meta = await self.store.get_session_meta(self.session_id) or {}
4213
4266
  working_history = await self.store.load_working_history(self.session_id)
4214
4267
 
4215
- content = user_text
4268
+ content: str | list[dict[str, Any]] = user_text # text and image refs once something is attached
4216
4269
  if not wake:
4217
4270
  # `/<skill> args`: only the args get @mentions and pastes; the SKILL.md text goes around them
4218
4271
  skill_run = parse_skill_command(user_text, self._skill_commands)
4219
4272
  mentions = skill_mentions(user_text, self._skill_commands) # what was typed, before anything expands
4220
4273
  expansion = await asyncio.to_thread(expand_file_mentions, skill_run[1] if skill_run else user_text,
4221
- self.config.max_tool_output_chars)
4274
+ self.config.max_tool_output_chars, images=self._images,
4275
+ file_lines=self.config.paste_file_lines)
4222
4276
  if expansion.attached:
4223
4277
  self._append("Attached " + ", ".join(expansion.attached), msg_type="system")
4224
4278
  if expansion.skipped:
4225
4279
  self._append("Not attached: " + "; ".join(expansion.skipped), msg_type="error")
4280
+ if expansion.refused:
4281
+ # An image that can't be sent stops the turn before hooks and history (multimodal D4, CON-006)
4282
+ self._append("Not attached: " + "; ".join(expansion.refused), msg_type="error")
4283
+ self._put_back_in_input([user_text])
4284
+ return
4226
4285
  # After the @mentions, so an "@" inside pasted text isn't taken as one
4227
4286
  content = await asyncio.to_thread(self._pastes.resolve, expansion.content, self.session_id,
4228
4287
  self.config.paste_file_lines, self.config.max_tool_output_chars)
@@ -4238,6 +4297,9 @@ class DostuffTUI(App):
4238
4297
  content = with_mention_note(content, mentions)
4239
4298
  if mentions:
4240
4299
  self._append(mention_line(mentions), msg_type="system")
4300
+ if expansion.parts: # text first, then the images (multimodal D10)
4301
+ content = [{"type": "text", "text": content}, *expansion.parts]
4302
+ self._append(ref_chips(content), msg_type="system")
4241
4303
 
4242
4304
  # Reset cancel state before the hooks below, so ESC can stop a slow one
4243
4305
  self.adapter._cancelled = False
@@ -4842,6 +4904,9 @@ class DostuffTUI(App):
4842
4904
  for i in range(len(self.steps_history) - 1, -1, -1):
4843
4905
  step = self.steps_history[i]
4844
4906
  content = step.get("content") if isinstance(step, dict) else None
4907
+ if (step.get("role") == "user" and isinstance(content, list) and not is_turn_context(step)
4908
+ and not is_tool_attachment_step(step)): # a prompt with images (multimodal REQ-1.4)
4909
+ return i
4845
4910
  if (step.get("role") == "user" and isinstance(content, str) and content != EMPTY_RESPONSE_NUDGE
4846
4911
  and not is_turn_context(step)
4847
4912
  and not content.startswith("[/undo]") and _parse_shell_step(content) is None
@@ -4927,6 +4992,18 @@ class DostuffTUI(App):
4927
4992
  self._show_picker("Search prompt history", [(f"h{i}", label(p)) for i, p in enumerate(prompts)], choose,
4928
4993
  filterable=True)
4929
4994
 
4995
+ async def action_paste_image(self) -> None:
4996
+ """Alt+V: the clipboard's image goes in the input as `[Image #N]` (multimodal REQ-3.1); the terminal's own
4997
+ paste (Ctrl+V) only ever carries text."""
4998
+ inp = self.query_one("#input", EnterSubmits)
4999
+ if not inp.display or inp.read_only:
5000
+ return
5001
+ data, message = await asyncio.to_thread(clipboard.read_clipboard_image)
5002
+ if data is None:
5003
+ self._flash_input_hint(message, seconds=4)
5004
+ return
5005
+ inp.insert_at_cursor(self._images.add(data))
5006
+
4930
5007
  # ── Exit ───────────────────────────────────────────────────────────────────
4931
5008
 
4932
5009
  def action_help_quit(self) -> None:
@@ -5072,6 +5149,10 @@ class DostuffTUI(App):
5072
5149
  # 4. Paste files, when loop.paste_retention_days is 0 (otherwise the startup sweep ages them out)
5073
5150
  if self.config.paste_retention_days <= 0:
5074
5151
  self._pastes.delete_files()
5152
+ # Attachments too, with loop.attachment_retention_days 0: this session's images and PDFs
5153
+ if self.config.attachment_retention_days <= 0:
5154
+ with contextlib.suppress(Exception):
5155
+ delete_attachments(self.steps_history)
5075
5156
  # 5. Session DB, after the agent rows and steps still queued for it (subagents D14)
5076
5157
  with contextlib.suppress(Exception):
5077
5158
  await asyncio.wait_for(_agent_registry().flush(), timeout=5.0)
@@ -18,6 +18,7 @@ RETIRED_STATUS_BAR_ITEMS = ("timer", "jobs")
18
18
  PASTE_COLLAPSE_LINES = 10
19
19
  PASTE_FILE_LINES = 200
20
20
  PASTE_RETENTION_DAYS = 7
21
+ ATTACHMENT_RETENTION_DAYS = 30
21
22
  AUTO_COMPACT_THRESHOLD = 50 # percent of the context window
22
23
  NOTIFY_KINDS = ("off", "bell", "osc9")
23
24
  NOTIFY_AFTER_SECONDS = 30.0
@@ -116,6 +117,9 @@ class Config:
116
117
  self.paste_file_lines = max(int(file_lines), 0) if file_lines is not None else PASTE_FILE_LINES
117
118
  days = loop_cfg.get("paste_retention_days")
118
119
  self.paste_retention_days = max(float(days), 0.0) if days is not None else PASTE_RETENTION_DAYS
120
+ # Images / PDFs copied into .dostuff/attachments/ (helpers/agent/attachments.py); 0 = delete with the session
121
+ days = loop_cfg.get("attachment_retention_days")
122
+ self.attachment_retention_days = max(float(days), 0.0) if days is not None else ATTACHMENT_RETENTION_DAYS
119
123
  # Model-call retries on rate limits / timeouts / 5xx: exponential backoff (or Retry-After), capped per wait
120
124
  retries = loop_cfg.get("max_retries")
121
125
  self.max_retries = max(int(retries), 0) if retries is not None else MAX_RETRIES
@@ -205,6 +209,27 @@ class Config:
205
209
  for e in raw_models if isinstance(e, dict) and e.get("name")
206
210
  ]
207
211
 
212
+ def model_capability(self, key: str) -> bool | None:
213
+ """`vision` / `pdf_input` for the active model from config.yaml: True / False, or None for `auto` (unset).
214
+
215
+ Read from the `models:` entry with the active model's name, else the `model:` block, for models litellm
216
+ has no metadata for (multimodal spec REQ-6.2)."""
217
+ name = self._raw_model_name()
218
+ entries = self.raw.get("models") or []
219
+ entry = next((e for e in entries if isinstance(e, dict) and e.get("name") and str(e["name"]) in (name, self.model_name)),
220
+ None) if isinstance(entries, list) else None
221
+ if entry is None:
222
+ entry = _block(self.raw, "model")
223
+ value = entry.get(key, "auto")
224
+ if isinstance(value, bool):
225
+ return value
226
+ text = str(value).strip().lower()
227
+ if text in ("true", "yes", "on", "1"):
228
+ return True
229
+ if text in ("false", "no", "off", "0"):
230
+ return False
231
+ return None
232
+
208
233
  def use_model(self, name: str, provider: str = "", api_key_env: str = "") -> None:
209
234
  """Switch the model for the rest of this process (/model); config.yaml is not changed."""
210
235
  self._session_model = {"name": name, "provider": provider}