agent-box-tool 0.1.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (304) hide show
  1. agent_box_tool-0.1.0/.github/workflows/aur-build.yml +64 -0
  2. agent_box_tool-0.1.0/.github/workflows/aur-publish.yml +49 -0
  3. agent_box_tool-0.1.0/.github/workflows/aur.yml +31 -0
  4. agent_box_tool-0.1.0/.github/workflows/release.yml +203 -0
  5. agent_box_tool-0.1.0/AGENTS.md +178 -0
  6. agent_box_tool-0.1.0/CHANGELOG.md +278 -0
  7. agent_box_tool-0.1.0/LICENSE +21 -0
  8. agent_box_tool-0.1.0/MANIFEST.in +7 -0
  9. agent_box_tool-0.1.0/PKG-INFO +176 -0
  10. agent_box_tool-0.1.0/README.md +149 -0
  11. agent_box_tool-0.1.0/agent_box/.containerignore +2 -0
  12. agent_box_tool-0.1.0/agent_box/Containerfile +720 -0
  13. agent_box_tool-0.1.0/agent_box/__init__.py +1 -0
  14. agent_box_tool-0.1.0/agent_box/__main__.py +8 -0
  15. agent_box_tool-0.1.0/agent_box/agent_profiles.py +152 -0
  16. agent_box_tool-0.1.0/agent_box/api_models.py +151 -0
  17. agent_box_tool-0.1.0/agent_box/atomicio.py +79 -0
  18. agent_box_tool-0.1.0/agent_box/aws_cloud.py +289 -0
  19. agent_box_tool-0.1.0/agent_box/branch_cleanup.py +267 -0
  20. agent_box_tool-0.1.0/agent_box/browser.py +239 -0
  21. agent_box_tool-0.1.0/agent_box/browser_client.py +36 -0
  22. agent_box_tool-0.1.0/agent_box/channel.py +272 -0
  23. agent_box_tool-0.1.0/agent_box/claude_settings.py +234 -0
  24. agent_box_tool-0.1.0/agent_box/cli.py +1069 -0
  25. agent_box_tool-0.1.0/agent_box/cloud.py +258 -0
  26. agent_box_tool-0.1.0/agent_box/codex_settings.py +57 -0
  27. agent_box_tool-0.1.0/agent_box/completion.bash +68 -0
  28. agent_box_tool-0.1.0/agent_box/completion.py +257 -0
  29. agent_box_tool-0.1.0/agent_box/completion.zsh +55 -0
  30. agent_box_tool-0.1.0/agent_box/config.py +1608 -0
  31. agent_box_tool-0.1.0/agent_box/config_menu.py +1526 -0
  32. agent_box_tool-0.1.0/agent_box/config_proposal.py +82 -0
  33. agent_box_tool-0.1.0/agent_box/container-launcher +9 -0
  34. agent_box_tool-0.1.0/agent_box/delegation.py +120 -0
  35. agent_box_tool-0.1.0/agent_box/errors.py +2 -0
  36. agent_box_tool-0.1.0/agent_box/external_config.py +382 -0
  37. agent_box_tool-0.1.0/agent_box/external_launch.py +386 -0
  38. agent_box_tool-0.1.0/agent_box/git_workflow.py +546 -0
  39. agent_box_tool-0.1.0/agent_box/github_review.py +531 -0
  40. agent_box_tool-0.1.0/agent_box/github_workflow.py +343 -0
  41. agent_box_tool-0.1.0/agent_box/host_k3s.py +430 -0
  42. agent_box_tool-0.1.0/agent_box/host_podman.py +229 -0
  43. agent_box_tool-0.1.0/agent_box/host_session.py +38 -0
  44. agent_box_tool-0.1.0/agent_box/identity.py +72 -0
  45. agent_box_tool-0.1.0/agent_box/image_build.py +95 -0
  46. agent_box_tool-0.1.0/agent_box/k3s.py +418 -0
  47. agent_box_tool-0.1.0/agent_box/keeper.sh +47 -0
  48. agent_box_tool-0.1.0/agent_box/kubeconfigs.py +318 -0
  49. agent_box_tool-0.1.0/agent_box/launch_options.py +333 -0
  50. agent_box_tool-0.1.0/agent_box/links.py +620 -0
  51. agent_box_tool-0.1.0/agent_box/local_workflow.py +94 -0
  52. agent_box_tool-0.1.0/agent_box/migrations.py +165 -0
  53. agent_box_tool-0.1.0/agent_box/model_catalog.py +116 -0
  54. agent_box_tool-0.1.0/agent_box/mounts.py +120 -0
  55. agent_box_tool-0.1.0/agent_box/nested_podman.py +127 -0
  56. agent_box_tool-0.1.0/agent_box/networking.py +169 -0
  57. agent_box_tool-0.1.0/agent_box/notify.py +690 -0
  58. agent_box_tool-0.1.0/agent_box/paths.py +242 -0
  59. agent_box_tool-0.1.0/agent_box/personal_browser.py +211 -0
  60. agent_box_tool-0.1.0/agent_box/plan_sync.py +288 -0
  61. agent_box_tool-0.1.0/agent_box/podman_doctor.py +87 -0
  62. agent_box_tool-0.1.0/agent_box/project_config.py +197 -0
  63. agent_box_tool-0.1.0/agent_box/provider_runner.py +435 -0
  64. agent_box_tool-0.1.0/agent_box/registries.py +456 -0
  65. agent_box_tool-0.1.0/agent_box/remote_control.py +471 -0
  66. agent_box_tool-0.1.0/agent_box/repo_binding.py +270 -0
  67. agent_box_tool-0.1.0/agent_box/review_results.py +217 -0
  68. agent_box_tool-0.1.0/agent_box/routing.py +58 -0
  69. agent_box_tool-0.1.0/agent_box/runtime.py +3916 -0
  70. agent_box_tool-0.1.0/agent_box/runtime_bundle.py +151 -0
  71. agent_box_tool-0.1.0/agent_box/selftest.py +170 -0
  72. agent_box_tool-0.1.0/agent_box/sessions.py +83 -0
  73. agent_box_tool-0.1.0/agent_box/skills/ab-adopt/SKILL.md +19 -0
  74. agent_box_tool-0.1.0/agent_box/skills/ab-config/SKILL.md +19 -0
  75. agent_box_tool-0.1.0/agent_box/skills/ab-interview/SKILL.md +16 -0
  76. agent_box_tool-0.1.0/agent_box/skills/ab-land/SKILL.md +19 -0
  77. agent_box_tool-0.1.0/agent_box/skills/ab-normalize/SKILL.md +14 -0
  78. agent_box_tool-0.1.0/agent_box/skills/ab-plan/SKILL.md +15 -0
  79. agent_box_tool-0.1.0/agent_box/skills/ab-pr/SKILL.md +20 -0
  80. agent_box_tool-0.1.0/agent_box/skills/ab-review/SKILL.md +21 -0
  81. agent_box_tool-0.1.0/agent_box/skills/ab-setup/SKILL.md +15 -0
  82. agent_box_tool-0.1.0/agent_box/skills/ab-setup/board-preparation.md +12 -0
  83. agent_box_tool-0.1.0/agent_box/skills/ab-sync/SKILL.md +23 -0
  84. agent_box_tool-0.1.0/agent_box/skills/ab-tracker/SKILL.md +32 -0
  85. agent_box_tool-0.1.0/agent_box/skills/ab-work/SKILL.md +27 -0
  86. agent_box_tool-0.1.0/agent_box/speed.py +29 -0
  87. agent_box_tool-0.1.0/agent_box/statusline.py +142 -0
  88. agent_box_tool-0.1.0/agent_box/text_delivery.py +276 -0
  89. agent_box_tool-0.1.0/agent_box/text_summary.py +84 -0
  90. agent_box_tool-0.1.0/agent_box/tmux.conf +34 -0
  91. agent_box_tool-0.1.0/agent_box/tracker/__init__.py +1 -0
  92. agent_box_tool-0.1.0/agent_box/tracker/adoption.py +314 -0
  93. agent_box_tool-0.1.0/agent_box/tracker/audit.py +133 -0
  94. agent_box_tool-0.1.0/agent_box/tracker/cli.py +516 -0
  95. agent_box_tool-0.1.0/agent_box/tracker/core.py +249 -0
  96. agent_box_tool-0.1.0/agent_box/tracker/extensions.py +178 -0
  97. agent_box_tool-0.1.0/agent_box/tracker/github.py +721 -0
  98. agent_box_tool-0.1.0/agent_box/tracker/github_api.py +388 -0
  99. agent_box_tool-0.1.0/agent_box/tracker/github_extensions.py +35 -0
  100. agent_box_tool-0.1.0/agent_box/tracker/jira.py +333 -0
  101. agent_box_tool-0.1.0/agent_box/tracker/jira_api.py +123 -0
  102. agent_box_tool-0.1.0/agent_box/tracker/registry.py +50 -0
  103. agent_box_tool-0.1.0/agent_box/tracker/vikunja.py +581 -0
  104. agent_box_tool-0.1.0/agent_box/tracker/vikunja_api.py +1338 -0
  105. agent_box_tool-0.1.0/agent_box/tracker/vikunja_board.py +213 -0
  106. agent_box_tool-0.1.0/agent_box/tracker/vikunja_clone.py +212 -0
  107. agent_box_tool-0.1.0/agent_box/tracker/vikunja_relations.py +100 -0
  108. agent_box_tool-0.1.0/agent_box/upgrades.py +90 -0
  109. agent_box_tool-0.1.0/agent_box/usage.py +528 -0
  110. agent_box_tool-0.1.0/agent_box/usage_auth.py +125 -0
  111. agent_box_tool-0.1.0/agent_box/workflow.py +2095 -0
  112. agent_box_tool-0.1.0/agent_box/workflow_behavior.py +43 -0
  113. agent_box_tool-0.1.0/agent_box/workflow_pause.py +151 -0
  114. agent_box_tool-0.1.0/agent_box/workflow_state.py +43 -0
  115. agent_box_tool-0.1.0/agent_box/workspace.py +77 -0
  116. agent_box_tool-0.1.0/agent_box/workspaces.py +263 -0
  117. agent_box_tool-0.1.0/agent_box_tool.egg-info/PKG-INFO +176 -0
  118. agent_box_tool-0.1.0/agent_box_tool.egg-info/SOURCES.txt +302 -0
  119. agent_box_tool-0.1.0/agent_box_tool.egg-info/dependency_links.txt +1 -0
  120. agent_box_tool-0.1.0/agent_box_tool.egg-info/entry_points.txt +2 -0
  121. agent_box_tool-0.1.0/agent_box_tool.egg-info/top_level.txt +1 -0
  122. agent_box_tool-0.1.0/docs/README.md +36 -0
  123. agent_box_tool-0.1.0/docs/compatibility.md +92 -0
  124. agent_box_tool-0.1.0/docs/configuration.md +289 -0
  125. agent_box_tool-0.1.0/docs/design/integrations.md +196 -0
  126. agent_box_tool-0.1.0/docs/design/native-launch.md +87 -0
  127. agent_box_tool-0.1.0/docs/design/networking.md +316 -0
  128. agent_box_tool-0.1.0/docs/design/third-party-notices.md +81 -0
  129. agent_box_tool-0.1.0/docs/design/tracker.md +227 -0
  130. agent_box_tool-0.1.0/docs/design/workflow-references.md +141 -0
  131. agent_box_tool-0.1.0/docs/design/workflow.md +356 -0
  132. agent_box_tool-0.1.0/docs/image.md +112 -0
  133. agent_box_tool-0.1.0/docs/installation.md +210 -0
  134. agent_box_tool-0.1.0/docs/integrations/README.md +31 -0
  135. agent_box_tool-0.1.0/docs/integrations/audio.md +42 -0
  136. agent_box_tool-0.1.0/docs/integrations/browser.md +194 -0
  137. agent_box_tool-0.1.0/docs/integrations/cloud-profiles.md +171 -0
  138. agent_box_tool-0.1.0/docs/integrations/external-providers.md +314 -0
  139. agent_box_tool-0.1.0/docs/integrations/git.md +57 -0
  140. agent_box_tool-0.1.0/docs/integrations/k3s.md +234 -0
  141. agent_box_tool-0.1.0/docs/integrations/kubeconfigs.md +118 -0
  142. agent_box_tool-0.1.0/docs/integrations/links.md +136 -0
  143. agent_box_tool-0.1.0/docs/integrations/registries.md +65 -0
  144. agent_box_tool-0.1.0/docs/integrations/remote-control.md +63 -0
  145. agent_box_tool-0.1.0/docs/integrations/skills.md +27 -0
  146. agent_box_tool-0.1.0/docs/integrations/telegram.md +76 -0
  147. agent_box_tool-0.1.0/docs/integrations/tracker.md +361 -0
  148. agent_box_tool-0.1.0/docs/integrations/workflow.md +497 -0
  149. agent_box_tool-0.1.0/docs/nested-podman.md +123 -0
  150. agent_box_tool-0.1.0/docs/networking.md +114 -0
  151. agent_box_tool-0.1.0/docs/releasing.md +286 -0
  152. agent_box_tool-0.1.0/docs/security.md +50 -0
  153. agent_box_tool-0.1.0/docs/troubleshooting.md +58 -0
  154. agent_box_tool-0.1.0/docs/usage.md +237 -0
  155. agent_box_tool-0.1.0/packaging/aur/LICENSE +12 -0
  156. agent_box_tool-0.1.0/packaging/aur/PKGBUILD.in +29 -0
  157. agent_box_tool-0.1.0/packaging/aur/known_hosts +2 -0
  158. agent_box_tool-0.1.0/pyproject.toml +54 -0
  159. agent_box_tool-0.1.0/setup.cfg +4 -0
  160. agent_box_tool-0.1.0/setup.py +12 -0
  161. agent_box_tool-0.1.0/tests/__init__.py +0 -0
  162. agent_box_tool-0.1.0/tests/api_model_samples/anthropic-page1.json +56 -0
  163. agent_box_tool-0.1.0/tests/api_model_samples/anthropic-page2.json +56 -0
  164. agent_box_tool-0.1.0/tests/api_model_samples/deepseek.json +60 -0
  165. agent_box_tool-0.1.0/tests/api_model_samples/openai.json +17 -0
  166. agent_box_tool-0.1.0/tests/api_model_samples/openrouter.json +215 -0
  167. agent_box_tool-0.1.0/tests/fixtures/state/import-state.json +7 -0
  168. agent_box_tool-0.1.0/tests/fixtures/state/review-budget.json +10 -0
  169. agent_box_tool-0.1.0/tests/github_fixtures.py +357 -0
  170. agent_box_tool-0.1.0/tests/live_github_tracker.py +107 -0
  171. agent_box_tool-0.1.0/tests/live_vikunja_adoption.py +182 -0
  172. agent_box_tool-0.1.0/tests/run_suite.py +72 -0
  173. agent_box_tool-0.1.0/tests/smoke_browser.py +143 -0
  174. agent_box_tool-0.1.0/tests/smoke_codex_sandbox.py +72 -0
  175. agent_box_tool-0.1.0/tests/test_agent_profiles.py +224 -0
  176. agent_box_tool-0.1.0/tests/test_agent_tree_mounts.py +230 -0
  177. agent_box_tool-0.1.0/tests/test_api_models.py +177 -0
  178. agent_box_tool-0.1.0/tests/test_apply.py +326 -0
  179. agent_box_tool-0.1.0/tests/test_atomicio.py +60 -0
  180. agent_box_tool-0.1.0/tests/test_audio.py +100 -0
  181. agent_box_tool-0.1.0/tests/test_aur.py +216 -0
  182. agent_box_tool-0.1.0/tests/test_aws_cloud.py +300 -0
  183. agent_box_tool-0.1.0/tests/test_branch_cleanup.py +1069 -0
  184. agent_box_tool-0.1.0/tests/test_browser.py +457 -0
  185. agent_box_tool-0.1.0/tests/test_browser_sidecar.py +189 -0
  186. agent_box_tool-0.1.0/tests/test_claude_channel.py +662 -0
  187. agent_box_tool-0.1.0/tests/test_claude_settings.py +330 -0
  188. agent_box_tool-0.1.0/tests/test_cli.py +307 -0
  189. agent_box_tool-0.1.0/tests/test_cloud.py +246 -0
  190. agent_box_tool-0.1.0/tests/test_codex_settings.py +88 -0
  191. agent_box_tool-0.1.0/tests/test_completion.py +363 -0
  192. agent_box_tool-0.1.0/tests/test_config.py +351 -0
  193. agent_box_tool-0.1.0/tests/test_config_ai.py +124 -0
  194. agent_box_tool-0.1.0/tests/test_config_describe.py +225 -0
  195. agent_box_tool-0.1.0/tests/test_config_menu.py +1050 -0
  196. agent_box_tool-0.1.0/tests/test_config_proposal.py +190 -0
  197. agent_box_tool-0.1.0/tests/test_config_set.py +114 -0
  198. agent_box_tool-0.1.0/tests/test_containerfile.py +318 -0
  199. agent_box_tool-0.1.0/tests/test_docs_links.py +262 -0
  200. agent_box_tool-0.1.0/tests/test_expand_user_paths.py +92 -0
  201. agent_box_tool-0.1.0/tests/test_external_config.py +277 -0
  202. agent_box_tool-0.1.0/tests/test_external_launch.py +380 -0
  203. agent_box_tool-0.1.0/tests/test_external_models.py +474 -0
  204. agent_box_tool-0.1.0/tests/test_external_workflow.py +156 -0
  205. agent_box_tool-0.1.0/tests/test_git_credentials.py +208 -0
  206. agent_box_tool-0.1.0/tests/test_github_review.py +761 -0
  207. agent_box_tool-0.1.0/tests/test_github_workflow.py +643 -0
  208. agent_box_tool-0.1.0/tests/test_host_exposure.py +308 -0
  209. agent_box_tool-0.1.0/tests/test_host_home.py +175 -0
  210. agent_box_tool-0.1.0/tests/test_host_k3s.py +505 -0
  211. agent_box_tool-0.1.0/tests/test_host_podman.py +187 -0
  212. agent_box_tool-0.1.0/tests/test_host_sessions.py +421 -0
  213. agent_box_tool-0.1.0/tests/test_identity.py +55 -0
  214. agent_box_tool-0.1.0/tests/test_image_build.py +158 -0
  215. agent_box_tool-0.1.0/tests/test_image_tools.py +136 -0
  216. agent_box_tool-0.1.0/tests/test_k3s.py +480 -0
  217. agent_box_tool-0.1.0/tests/test_k3s_runtime.py +333 -0
  218. agent_box_tool-0.1.0/tests/test_kubeconfigs.py +352 -0
  219. agent_box_tool-0.1.0/tests/test_launch_options.py +260 -0
  220. agent_box_tool-0.1.0/tests/test_links.py +491 -0
  221. agent_box_tool-0.1.0/tests/test_local_workflow.py +906 -0
  222. agent_box_tool-0.1.0/tests/test_managed_skills.py +327 -0
  223. agent_box_tool-0.1.0/tests/test_migrations.py +270 -0
  224. agent_box_tool-0.1.0/tests/test_model_catalog.py +187 -0
  225. agent_box_tool-0.1.0/tests/test_mounts.py +116 -0
  226. agent_box_tool-0.1.0/tests/test_nested_launch.py +181 -0
  227. agent_box_tool-0.1.0/tests/test_nested_podman.py +345 -0
  228. agent_box_tool-0.1.0/tests/test_nested_podman_data.py +263 -0
  229. agent_box_tool-0.1.0/tests/test_networking.py +202 -0
  230. agent_box_tool-0.1.0/tests/test_notify.py +765 -0
  231. agent_box_tool-0.1.0/tests/test_package_metadata.py +93 -0
  232. agent_box_tool-0.1.0/tests/test_paths.py +146 -0
  233. agent_box_tool-0.1.0/tests/test_permission_modes.py +126 -0
  234. agent_box_tool-0.1.0/tests/test_personal_browser.py +352 -0
  235. agent_box_tool-0.1.0/tests/test_plan_sync.py +466 -0
  236. agent_box_tool-0.1.0/tests/test_podman_doctor.py +92 -0
  237. agent_box_tool-0.1.0/tests/test_project_config.py +443 -0
  238. agent_box_tool-0.1.0/tests/test_provider_runner.py +491 -0
  239. agent_box_tool-0.1.0/tests/test_registries.py +391 -0
  240. agent_box_tool-0.1.0/tests/test_release.py +199 -0
  241. agent_box_tool-0.1.0/tests/test_remote_control.py +463 -0
  242. agent_box_tool-0.1.0/tests/test_repository_guidance.py +125 -0
  243. agent_box_tool-0.1.0/tests/test_review_results.py +489 -0
  244. agent_box_tool-0.1.0/tests/test_review_routing.py +195 -0
  245. agent_box_tool-0.1.0/tests/test_reviewer_routes.py +90 -0
  246. agent_box_tool-0.1.0/tests/test_routing.py +141 -0
  247. agent_box_tool-0.1.0/tests/test_runtime.py +1104 -0
  248. agent_box_tool-0.1.0/tests/test_runtime_bundle.py +176 -0
  249. agent_box_tool-0.1.0/tests/test_runtime_isolation.py +64 -0
  250. agent_box_tool-0.1.0/tests/test_selftest.py +40 -0
  251. agent_box_tool-0.1.0/tests/test_speed.py +179 -0
  252. agent_box_tool-0.1.0/tests/test_statusline.py +294 -0
  253. agent_box_tool-0.1.0/tests/test_suite_runner.py +56 -0
  254. agent_box_tool-0.1.0/tests/test_text_delivery.py +260 -0
  255. agent_box_tool-0.1.0/tests/test_tmux_sessions.py +270 -0
  256. agent_box_tool-0.1.0/tests/test_tool_cache.py +147 -0
  257. agent_box_tool-0.1.0/tests/test_tracker_access.py +118 -0
  258. agent_box_tool-0.1.0/tests/test_tracker_adapter.py +97 -0
  259. agent_box_tool-0.1.0/tests/test_tracker_adoption.py +179 -0
  260. agent_box_tool-0.1.0/tests/test_tracker_board_plan.py +207 -0
  261. agent_box_tool-0.1.0/tests/test_tracker_config.py +66 -0
  262. agent_box_tool-0.1.0/tests/test_tracker_github.py +294 -0
  263. agent_box_tool-0.1.0/tests/test_tracker_github_setup.py +157 -0
  264. agent_box_tool-0.1.0/tests/test_tracker_github_workflow.py +112 -0
  265. agent_box_tool-0.1.0/tests/test_tracker_github_write.py +239 -0
  266. agent_box_tool-0.1.0/tests/test_tracker_imports.py +849 -0
  267. agent_box_tool-0.1.0/tests/test_tracker_jira.py +349 -0
  268. agent_box_tool-0.1.0/tests/test_tracker_lifecycle.py +117 -0
  269. agent_box_tool-0.1.0/tests/test_tracker_maintenance.py +556 -0
  270. agent_box_tool-0.1.0/tests/test_tracker_normalization.py +140 -0
  271. agent_box_tool-0.1.0/tests/test_tracker_priority.py +42 -0
  272. agent_box_tool-0.1.0/tests/test_tracker_resolution.py +235 -0
  273. agent_box_tool-0.1.0/tests/test_tracker_setup.py +154 -0
  274. agent_box_tool-0.1.0/tests/test_tracker_staging.py +795 -0
  275. agent_box_tool-0.1.0/tests/test_tracker_transport.py +187 -0
  276. agent_box_tool-0.1.0/tests/test_tracker_workflow.py +130 -0
  277. agent_box_tool-0.1.0/tests/test_uninstall.py +338 -0
  278. agent_box_tool-0.1.0/tests/test_upgrades.py +139 -0
  279. agent_box_tool-0.1.0/tests/test_usage.py +258 -0
  280. agent_box_tool-0.1.0/tests/test_usage_auth.py +386 -0
  281. agent_box_tool-0.1.0/tests/test_usage_blocks.py +101 -0
  282. agent_box_tool-0.1.0/tests/test_user_env.py +206 -0
  283. agent_box_tool-0.1.0/tests/test_workflow_behavior.py +233 -0
  284. agent_box_tool-0.1.0/tests/test_workflow_branches.py +272 -0
  285. agent_box_tool-0.1.0/tests/test_workflow_config.py +264 -0
  286. agent_box_tool-0.1.0/tests/test_workflow_delegate.py +352 -0
  287. agent_box_tool-0.1.0/tests/test_workflow_delta_review.py +140 -0
  288. agent_box_tool-0.1.0/tests/test_workflow_finish.py +941 -0
  289. agent_box_tool-0.1.0/tests/test_workflow_git.py +202 -0
  290. agent_box_tool-0.1.0/tests/test_workflow_inspect.py +275 -0
  291. agent_box_tool-0.1.0/tests/test_workflow_pause.py +271 -0
  292. agent_box_tool-0.1.0/tests/test_workflow_review.py +781 -0
  293. agent_box_tool-0.1.0/tests/test_workflow_text_delivery.py +391 -0
  294. agent_box_tool-0.1.0/tests/test_working_language.py +321 -0
  295. agent_box_tool-0.1.0/tests/test_workspace.py +135 -0
  296. agent_box_tool-0.1.0/tests/test_workspace_container.py +917 -0
  297. agent_box_tool-0.1.0/tests/test_workspaces.py +261 -0
  298. agent_box_tool-0.1.0/tests/tracker_fixtures.py +287 -0
  299. agent_box_tool-0.1.0/tests/workflow_fixtures.py +227 -0
  300. agent_box_tool-0.1.0/tools/aur.py +203 -0
  301. agent_box_tool-0.1.0/tools/markdown_links.py +71 -0
  302. agent_box_tool-0.1.0/tools/package_metadata.py +41 -0
  303. agent_box_tool-0.1.0/tools/release.py +217 -0
  304. agent_box_tool-0.1.0/tools/text_transport_fixture.py +586 -0
@@ -0,0 +1,64 @@
1
+ name: Build Arch package
2
+
3
+ on:
4
+ workflow_call:
5
+ inputs:
6
+ version:
7
+ required: true
8
+ type: string
9
+ revision:
10
+ default: '1'
11
+ type: string
12
+ distributions-id:
13
+ description: 'Checked distribution artifact from this run; empty fetches an existing release'
14
+ default: ''
15
+ type: string
16
+ outputs:
17
+ artifact-id:
18
+ value: ${{ jobs.build.outputs.artifact-id }}
19
+
20
+ permissions:
21
+ contents: read
22
+
23
+ jobs:
24
+ build:
25
+ if: github.repository == 'rus364/agent-box'
26
+ runs-on: ubuntu-24.04
27
+ timeout-minutes: 20
28
+ outputs:
29
+ artifact-id: ${{ steps.upload.outputs.artifact-id }}
30
+ steps:
31
+ - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
32
+ with:
33
+ persist-credentials: false
34
+ - uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
35
+ if: inputs.distributions-id != ''
36
+ with:
37
+ artifact-ids: ${{ inputs.distributions-id }}
38
+ path: dist
39
+ merge-multiple: true
40
+ digest-mismatch: error
41
+ - name: Build and verify source in Arch
42
+ env:
43
+ DISTRIBUTIONS_ID: ${{ inputs.distributions-id }}
44
+ PACKAGE_VERSION: ${{ inputs.version }}
45
+ PACKAGE_REVISION: ${{ inputs.revision }}
46
+ run: |
47
+ mkdir -p "$RUNNER_TEMP/arch-result"
48
+ args=(release /result "$PACKAGE_VERSION" "$PACKAGE_REVISION")
49
+ if [[ -n "$DISTRIBUTIONS_ID" ]]; then
50
+ archives=(dist/*.tar.gz)
51
+ [[ ${#archives[@]} == 1 && -f "${archives[0]}" ]]
52
+ args=(artifact /result "$PACKAGE_VERSION" "$PACKAGE_REVISION" "/repo/${archives[0]}")
53
+ fi
54
+ docker run --rm -v "$GITHUB_WORKSPACE:/repo:ro" -v "$RUNNER_TEMP/arch-result:/result" \
55
+ archlinux:base@sha256:363129b67b2bc6c5a634f8fb4961a7e2eba213a2ec075d159127b1260290a722 \
56
+ bash /repo/tools/check_arch.sh "${args[@]}"
57
+ - uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
58
+ id: upload
59
+ with:
60
+ name: aur-metadata
61
+ path: ${{ runner.temp }}/arch-result/metadata/
62
+ include-hidden-files: true
63
+ if-no-files-found: error
64
+ retention-days: 30
@@ -0,0 +1,49 @@
1
+ name: Publish AUR metadata
2
+
3
+ on:
4
+ workflow_call:
5
+ secrets:
6
+ AUR_SSH_PRIVATE_KEY:
7
+ required: true
8
+ inputs:
9
+ artifact-id:
10
+ required: true
11
+ type: string
12
+
13
+ permissions:
14
+ contents: read
15
+
16
+ jobs:
17
+ publish:
18
+ if: github.repository == 'rus364/agent-box'
19
+ runs-on: ubuntu-24.04
20
+ timeout-minutes: 10
21
+ environment: aur
22
+ concurrency:
23
+ group: aur-agent-box-publication
24
+ cancel-in-progress: false
25
+ steps:
26
+ - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
27
+ with:
28
+ persist-credentials: false
29
+ - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
30
+ with:
31
+ python-version: '3.11'
32
+ - uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
33
+ with:
34
+ artifact-ids: ${{ inputs.artifact-id }}
35
+ path: aur-metadata
36
+ merge-multiple: true
37
+ digest-mismatch: error
38
+ - name: Push checked metadata to AUR
39
+ env:
40
+ AUR_SSH_PRIVATE_KEY: ${{ secrets.AUR_SSH_PRIVATE_KEY }}
41
+ run: |
42
+ umask 077
43
+ keydir=$(mktemp -d)
44
+ trap 'rm -rf "$keydir"' EXIT
45
+ test -n "$AUR_SSH_PRIVATE_KEY"
46
+ printf '%s\n' "$AUR_SSH_PRIVATE_KEY" > "$keydir/id_ed25519"
47
+ unset AUR_SSH_PRIVATE_KEY
48
+ export GIT_SSH_COMMAND="ssh -i $keydir/id_ed25519 -o IdentitiesOnly=yes -o BatchMode=yes -o StrictHostKeyChecking=yes -o UserKnownHostsFile=$GITHUB_WORKSPACE/packaging/aur/known_hosts"
49
+ python tools/aur.py publish --directory aur-metadata
@@ -0,0 +1,31 @@
1
+ name: AUR
2
+
3
+ on:
4
+ workflow_dispatch:
5
+ inputs:
6
+ version:
7
+ description: 'Existing stable GitHub/PyPI release (e.g. 1.0.1)'
8
+ required: true
9
+ type: string
10
+ revision:
11
+ description: 'Arch pkgrel (increase for packaging-only corrections)'
12
+ default: '1'
13
+ type: string
14
+
15
+ permissions:
16
+ contents: read
17
+
18
+ jobs:
19
+ build:
20
+ uses: ./.github/workflows/aur-build.yml
21
+ with:
22
+ version: ${{ inputs.version }}
23
+ revision: ${{ inputs.revision }}
24
+
25
+ publish:
26
+ needs: build
27
+ uses: ./.github/workflows/aur-publish.yml
28
+ secrets:
29
+ AUR_SSH_PRIVATE_KEY: ${{ secrets.AUR_SSH_PRIVATE_KEY }}
30
+ with:
31
+ artifact-id: ${{ needs.build.outputs.artifact-id }}
@@ -0,0 +1,203 @@
1
+ name: Release
2
+
3
+ on:
4
+ push:
5
+ tags: ['v*.*.*']
6
+
7
+ permissions:
8
+ contents: read
9
+
10
+ concurrency:
11
+ group: release-${{ github.ref }}
12
+ cancel-in-progress: false
13
+
14
+ env:
15
+ RELEASE_TAG: ${{ github.ref_name }}
16
+
17
+ jobs:
18
+ tests:
19
+ runs-on: ubuntu-24.04
20
+ timeout-minutes: 15
21
+ strategy:
22
+ fail-fast: false
23
+ matrix:
24
+ python: ['3.11', '3.12', '3.13', '3.14']
25
+ steps:
26
+ - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
27
+ with:
28
+ persist-credentials: false
29
+ - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
30
+ with:
31
+ python-version: ${{ matrix.python }}
32
+ - run: python tools/release.py tag
33
+ - run: python -m agent_box selftest
34
+ - run: python tests/run_suite.py
35
+
36
+ build:
37
+ runs-on: ubuntu-24.04
38
+ timeout-minutes: 20
39
+ outputs:
40
+ artifact-id: ${{ steps.upload.outputs.artifact-id }}
41
+ notes-id: ${{ steps.notes.outputs.artifact-id }}
42
+ version: ${{ steps.identity.outputs.version }}
43
+ steps:
44
+ - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
45
+ with:
46
+ persist-credentials: false
47
+ - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
48
+ with:
49
+ python-version: '3.11'
50
+ - run: python tools/release.py tag
51
+ - name: Read release version
52
+ id: identity
53
+ run: python -c 'import tomllib; print("version=" + tomllib.load(open("pyproject.toml", "rb"))["project"]["version"])' >> "$GITHUB_OUTPUT"
54
+ - name: Install release tools
55
+ run: python -m pip install build==1.6.1 twine==7.0.0 pipx==1.18.3 uv==0.13.1 ruff==0.17.1
56
+ - name: Run Ruff
57
+ run: ruff check --select E4,E9,F agent_box/ tests/ tools/ setup.py
58
+ - name: Build and validate both distributions
59
+ run: |
60
+ SOURCE_DATE_EPOCH=$(git log -1 --format=%ct)
61
+ export SOURCE_DATE_EPOCH
62
+ python -m build
63
+ python -m twine check --strict dist/*
64
+ python tools/release.py artifacts --install
65
+ python tools/release.py notes > release-notes.md
66
+ sha256sum dist/*
67
+ - uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
68
+ id: upload
69
+ with:
70
+ name: distributions
71
+ path: dist/*
72
+ if-no-files-found: error
73
+ compression-level: 0
74
+ retention-days: 30
75
+ - uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
76
+ id: notes
77
+ with:
78
+ name: release-notes
79
+ path: release-notes.md
80
+ if-no-files-found: error
81
+ retention-days: 30
82
+
83
+ publish-test:
84
+ needs: [tests, build]
85
+ if: github.repository == 'rus364/agent-box'
86
+ runs-on: ubuntu-24.04
87
+ timeout-minutes: 10
88
+ environment:
89
+ name: testpypi
90
+ url: https://test.pypi.org/p/agent-box-tool
91
+ permissions:
92
+ id-token: write
93
+ steps:
94
+ - uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
95
+ with:
96
+ artifact-ids: ${{ needs.build.outputs.artifact-id }}
97
+ path: dist
98
+ merge-multiple: true
99
+ digest-mismatch: error
100
+ - uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 # v1.14.2
101
+ with:
102
+ repository-url: https://test.pypi.org/legacy/
103
+
104
+ verify-test:
105
+ needs: [build, publish-test]
106
+ runs-on: ubuntu-24.04
107
+ timeout-minutes: 15
108
+ steps:
109
+ - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
110
+ with:
111
+ persist-credentials: false
112
+ - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
113
+ with:
114
+ python-version: '3.11'
115
+ - uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
116
+ with:
117
+ artifact-ids: ${{ needs.build.outputs.artifact-id }}
118
+ path: dist
119
+ merge-multiple: true
120
+ digest-mismatch: error
121
+ - run: python -m pip install pipx==1.18.3 uv==0.13.1
122
+ - run: python tools/release.py index --index testpypi
123
+
124
+ publish:
125
+ needs: [build, verify-test]
126
+ if: github.repository == 'rus364/agent-box'
127
+ runs-on: ubuntu-24.04
128
+ timeout-minutes: 10
129
+ environment:
130
+ name: pypi
131
+ url: https://pypi.org/p/agent-box-tool
132
+ permissions:
133
+ id-token: write
134
+ steps:
135
+ - uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
136
+ with:
137
+ artifact-ids: ${{ needs.build.outputs.artifact-id }}
138
+ path: dist
139
+ merge-multiple: true
140
+ digest-mismatch: error
141
+ - uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 # v1.14.2
142
+
143
+ verify:
144
+ needs: [build, publish]
145
+ runs-on: ubuntu-24.04
146
+ timeout-minutes: 15
147
+ steps:
148
+ - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
149
+ with:
150
+ persist-credentials: false
151
+ - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
152
+ with:
153
+ python-version: '3.11'
154
+ - uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
155
+ with:
156
+ artifact-ids: ${{ needs.build.outputs.artifact-id }}
157
+ path: dist
158
+ merge-multiple: true
159
+ digest-mismatch: error
160
+ - run: python -m pip install pipx==1.18.3 uv==0.13.1
161
+ - run: python tools/release.py index --index pypi
162
+
163
+ github-release:
164
+ needs: [build, verify]
165
+ if: github.repository == 'rus364/agent-box'
166
+ runs-on: ubuntu-24.04
167
+ timeout-minutes: 10
168
+ permissions:
169
+ contents: write
170
+ steps:
171
+ - uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
172
+ with:
173
+ artifact-ids: ${{ needs.build.outputs.artifact-id }}
174
+ path: dist
175
+ merge-multiple: true
176
+ digest-mismatch: error
177
+ - uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
178
+ with:
179
+ artifact-ids: ${{ needs.build.outputs.notes-id }}
180
+ path: .
181
+ merge-multiple: true
182
+ digest-mismatch: error
183
+ - name: Publish the checked distributions and changelog entry
184
+ env:
185
+ GH_TOKEN: ${{ github.token }}
186
+ run: >-
187
+ gh release create "$RELEASE_TAG" dist/* --repo "$GITHUB_REPOSITORY"
188
+ --verify-tag --latest --title "$RELEASE_TAG" --notes-file release-notes.md
189
+
190
+ arch:
191
+ needs: build
192
+ uses: ./.github/workflows/aur-build.yml
193
+ with:
194
+ version: ${{ needs.build.outputs.version }}
195
+ distributions-id: ${{ needs.build.outputs.artifact-id }}
196
+
197
+ aur:
198
+ needs: [arch, github-release]
199
+ uses: ./.github/workflows/aur-publish.yml
200
+ secrets:
201
+ AUR_SSH_PRIVATE_KEY: ${{ secrets.AUR_SSH_PRIVATE_KEY }}
202
+ with:
203
+ artifact-id: ${{ needs.arch.outputs.artifact-id }}
@@ -0,0 +1,178 @@
1
+ <!-- BEGIN AGENT-BOX workflow sha256=9946c7a642bb314e71d827edf9d50639105dac9ee0ce411bb8daedca3d90767e -->
2
+ Read the tracked task before work; .agent-box.json binds this repository to its tracker project.
3
+ Coordinators: before planning or implementation, read `agent-box workflow behavior --role coordinator` and follow its effective instructions and startup guidance notice. Delegates follow their own role's behavior supplied in the assignment; never load coordinator behavior.
4
+ Use agent-box tracker for task state, progress and dependencies; read related history when context is missing.
5
+ Use ab-interview, ab-plan, ab-work, ab-sync, ab-review, ab-pr, and ab-land as needed. ab-setup maintains this binding and ab-adopt brings an existing project in line with the workflow; ab-normalize processes unmarked tasks in a bound project.
6
+ The coordinator owns branches, commits, lifecycle, dependencies, and GitHub actions. Delegate implementation sequentially and research to scouts, which may run in parallel, when their model lists are configured; with an empty list the coordinator does that work itself.
7
+ A worker changes project files and answers; scouts and a fresh reviewer only read. Plan sync reads the repository and updates tracker descriptions and comments through agent-box tracker; it never changes project files, Git or lifecycle. The coordinator verifies answers and findings and commits what it accepts.
8
+ Tracker comments are a human journal. Branch, base branch, and pull request come from Git and GitHub; lifecycle comes from the tracker's own fields, never from comment text.
9
+ Use the user's language for all coordinator messages to them: progress updates, questions, option explanations and final answers. Literal project labels may stay quoted in the project language. Write tracker text in the `language` that `agent-box tracker status` reports; when null, create new tasks in the user's interaction language and preserve existing tasks' language. Write code comments, docstrings, documentation, commits, PRs and review replies in `configuration.engineering_language` from `agent-box workflow inspect`. Report conflicts with repository language requirements before editing; preserve user-owned instructions. Agent-to-agent handoffs and reports stay English; agent-box CLI output, errors and help stay English.
10
+ Complete subtasks only after validation and integration into the parent branch; complete parents only after merge into the base branch.
11
+ <!-- END AGENT-BOX workflow -->
12
+
13
+ # agent-box — notes for agents working on this repository
14
+
15
+ ## What this is
16
+
17
+ A launcher. `agent-box` runs Claude Code and Codex CLI inside rootless Podman
18
+ workspace boxes. Python standard library at runtime, packaged as `agent-box-tool` with no
19
+ runtime dependencies. Install editable for development; uv/pipx or pacman own the public
20
+ `agent-box` command and package updates.
21
+
22
+ ```text
23
+ pyproject.toml package metadata and agent-box -> agent_box.cli:main
24
+ agent_box/cli.py argument parsing and command dispatch
25
+ agent_box/config_menu.py stdlib curses configuration menu
26
+ agent_box/tracker/ portable task contract and product adapters
27
+ agent_box/workflow.py deterministic workflow boundaries; skills orchestrate
28
+ agent_box/runtime.py container lifecycle, mounts, launches, doctor
29
+ agent_box/config.py the whole config schema; flat dataclasses, no framework
30
+ agent_box/paths.py every host-side path; nothing else may hardcode a home layout
31
+ agent_box/runtime_bundle.py immutable package copies for running boxes
32
+ agent_box/skills/ skills agent-box ships and installs (owned, checked in)
33
+ agent_box/Containerfile the workspace image, with optional tool groups
34
+ tests/ unittest, no plugins
35
+ ```
36
+
37
+ ## Rules that are not negotiable
38
+
39
+ **Experimental 0.x releases.** Use SemVer's initial-development line, starting
40
+ at 0.1.0. Interfaces, configuration and stored formats may change without
41
+ compatibility guarantees; breaking changes do not require a 1.x release.
42
+ Describe changes and required fresh setup in release notes. Published artifacts
43
+ remain immutable. Package versions and persisted schema versions are separate;
44
+ see `docs/compatibility.md`.
45
+
46
+ **No historical compatibility support during 0.x.** Do not add historical
47
+ migrations, legacy aliases, compatibility fallbacks, transition releases or an
48
+ old-version upgrade matrix before a new 1.x line. A future stable policy requires
49
+ a separate explicit decision; it does not revive support for the former releases.
50
+ Keep the generic schema and storage machinery for future use, but no historical
51
+ conversion handlers.
52
+ Retain current schema identities when package numbering changes. Reject
53
+ unsupported or future formats before overwriting them; never silently reset or
54
+ delete user data. Test current behavior and storage safety. Running workspace
55
+ runtimes stay immutable; adopting a new runtime requires explicit stop/relaunch.
56
+
57
+ **Paths come from `paths.py`.** Use `HOST_HOME` (passwd-derived), never
58
+ `Path.home()`, `os.path.expanduser`, or `$HOME`. A poisoned environment must not
59
+ be able to move a bind mount, a state directory or the container's home.
60
+
61
+ **Off by default.** Anything that exposes a credential or widens what an agent
62
+ can reach starts disabled. The exceptions are documented in the dataclass that
63
+ defines them, with the reason.
64
+
65
+ **Apply once after a package update.** `runtime.apply_config` is the single
66
+ integration writer. Configuration commands apply explicit changes; the first
67
+ host launch after a package update validates the saved format and refreshes
68
+ already configured integrations under a lock, recording the package identity
69
+ only after success. Unchanged launches and read-only commands do not reapply.
70
+ Rendered sessions never infer or rewrite unavailable host settings. Preserve
71
+ user-owned content and opt-ins; keep `config apply` for manual edits and retry,
72
+ and `uninstall` for removing owned integrations.
73
+
74
+ On-demand Claude usage may renew and atomically save its OAuth credentials;
75
+ this is authentication maintenance, not integration application. Status-line
76
+ reads never renew tokens. Coordinate credential writes with Claude's locks.
77
+
78
+ **Installation belongs to the installer.** uv/pipx or pacman own installed
79
+ commands and package updates; uv/pipx also own their shell PATH setup. agent-box never edits shell startup files or installer entry points.
80
+ After upgrading the package, the next host launch refreshes integrations;
81
+ run `agent-box uninstall` before removing the package through its installer.
82
+
83
+ **agent-box owns its integrations.** An integration configured somewhere else,
84
+ that the user has to assemble first, is not an integration. Settings live in
85
+ `config.json`; skills are shipped in `agent_box/skills/` and installed by
86
+ agent-box; the container gets a rendered, minimal artifact, never `config.json`
87
+ itself.
88
+
89
+ **Derived, not stored.** A fact that Git, GitHub or the tracker already owns is
90
+ read back from there. Branch names come from the task's `ab/<id>-` namespace,
91
+ the base branch from origin's default, the pull request from a head/base lookup,
92
+ the lifecycle from the board's own columns. `.agent-box.json` names the tracker
93
+ project and holds the allowed project configuration overrides. Nothing machine-readable is written into a tracker
94
+ comment: a comment is a human journal, and lifecycle is read from the tracker's
95
+ own fields.
96
+
97
+ **Role ownership.** Plan sync may update tracker descriptions and comments through
98
+ `agent-box tracker`, reading project files without changing them. The coordinator
99
+ owns Git, lifecycle, dependencies and GitHub. Other roles keep their existing limits.
100
+
101
+ **The coordinator accepts implementation.** A delegated worker reads its brief and
102
+ the code, changes project files in the working tree, and answers in Markdown;
103
+ a reviewer or scout reads and reports, changing nothing at all. The
104
+ coordinator decides from that answer what to commit and what to record in the
105
+ tracker and on GitHub. This is a contract, not credential isolation: a
106
+ delegation runs either as a native subagent of the coordinator's own session or
107
+ as a managed `codex exec` / `claude -p`, the first of which inherits the
108
+ coordinator's workspace, `.git` and credentials, so the two backends
109
+ deliberately share one contract rather than one of them acquiring private
110
+ restrictions. Workers and scouts are therefore only launched (`workflow
111
+ delegate`), never tracked: guards that only existed because the contract was
112
+ wide belong deleted, not tightened. A reviewer round is still bound to its
113
+ repository, project, task and scope by the descriptor workflow keeps beside the
114
+ round's input, which is plain readable JSON and is deliberately not treated as
115
+ unforgeable; a native reviewer's model and context are taken on trust.
116
+
117
+ **Secrets travel by name.** `--env=NAME` (Podman inherits the value) for
118
+ anything secret; `--env=NAME=VALUE` puts the value in an argv that `/proc`
119
+ exposes to other processes. `notify.sync_credentials` and
120
+ `runtime.sync_tracker_runtime` are the pattern for rendered credential files.
121
+
122
+ **Never overwrite what a user owns.** Skill directories carry a marker; ones
123
+ without it are the user's. Claude's `statusLine` slot is filled only when empty.
124
+ Hook removal only ever touches agent-box's own commands.
125
+
126
+ ## Working in the code
127
+
128
+ - **All text an agent may read must be functionally compact.** Skills, instructions,
129
+ handoffs, messages, errors, hints, CLI help and command output need enough context,
130
+ exact commands and necessary constraints to act without guessing; remove filler
131
+ and repetition without cryptic compression.
132
+ - **Comments explain why, not what.** The existing docstrings state the decision
133
+ and the alternative that was rejected. Match that; do not add narration.
134
+ - **Tests are the specification.** Every test's name and docstring says what
135
+ behaviour is being protected and why it would be wrong otherwise. A test that
136
+ restates the implementation is noise.
137
+ - **Structural vs per-exec.** Anything in `container_lifetime_args` is part of
138
+ the box's identity: changing it recreates the box. Per-invocation values go
139
+ through `invocation_env`. Choose deliberately.
140
+ - **Diagnostics are returned, not printed**, so both the launch path and
141
+ `agent-box config` can render them (`tracker_warnings` is the pattern).
142
+
143
+ ## Commands
144
+
145
+ ```bash
146
+ python3 tests/run_suite.py # full suite; isolated paths, no outer PTY
147
+ python3 -m agent_box selftest # fast, no Podman
148
+ uvx ruff check --select E4,E9,F agent_box/ tests/ # what CI lints
149
+ python3 -m agent_box config show # inspect the live config, tokens redacted
150
+ ```
151
+
152
+ The runner uses unittest discovery, temporary state/integration paths and piped
153
+ stdio. For focused runs: `python3 tests/run_suite.py discover -s tests -p test_browser.py`.
154
+ Test modules import each other by bare name, so keep discovery.
155
+
156
+ ## Gotchas
157
+
158
+ - `tests/` must never touch the developer's real `~/.claude` or `~/.agents`.
159
+ Anything that calls `config_interactive` or `apply_config` has to patch
160
+ `runtime.CLAUDE_HOME`, `runtime.CODEX_HOME`, `runtime.AGENT_SKILLS_DIR`, `runtime.MANAGED_SKILLS_SOURCE`
161
+ and the credential paths. This has bitten before.
162
+ - Module-level constants derived from `paths.py` (`AGENTS_DIR`, `TRACKER_RUNTIME_DIR`,
163
+ `CONTAINER_TRACKER_RUNTIME_DIR`) are resolved at import; tests patch them on `runtime`,
164
+ not on `paths`.
165
+ - `tests/run_suite.py` and `selftest` drop every inherited `AGENT_BOX_*` variable,
166
+ so they pass inside a workspace box as is; a bare `python3 -m unittest` does not,
167
+ and reads the session's `AGENT_BOX_RUNTIME_CONFIG` instead of its fixtures.
168
+ - The image label `io.agent-box.tools` records the built tool groups. A missing
169
+ label means *unknown*, not *empty* — never report it as drift.
170
+ - Inside a workspace box the saved configuration is not mounted: `config apply`
171
+ then applies only the skills and profiles the rendered session snapshot
172
+ describes and leaves host-only sections (notifications, hooks, status line,
173
+ credentials, Claude links) alone; the global `agent-box config` menu
174
+ refuses because it edits a file that is not there.
175
+ - `agent_box/skills/` contains short owned `ab-*` skills. Maintain them directly
176
+ and keep their command/role contracts consistent with the Python helpers.
177
+ - `.gitignore` ignores `/skills/` at the repo root only — `agent_box/skills/` is
178
+ checked in on purpose.