agent-pbx 2.1.0__tar.gz → 2.2.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 (168) hide show
  1. {agent_pbx-2.1.0 → agent_pbx-2.2.0}/PKG-INFO +308 -56
  2. agent_pbx-2.1.0/src/agent_pbx.egg-info/PKG-INFO → agent_pbx-2.2.0/README.md +299 -85
  3. {agent_pbx-2.1.0 → agent_pbx-2.2.0}/pyproject.toml +12 -0
  4. {agent_pbx-2.1.0 → agent_pbx-2.2.0}/src/agent_pbx/__init__.py +1 -1
  5. {agent_pbx-2.1.0 → agent_pbx-2.2.0}/src/agent_pbx/agent_adoption.py +10 -3
  6. {agent_pbx-2.1.0 → agent_pbx-2.2.0}/src/agent_pbx/api.py +419 -51
  7. {agent_pbx-2.1.0 → agent_pbx-2.2.0}/src/agent_pbx/cli.py +453 -0
  8. agent_pbx-2.2.0/src/agent_pbx/codex/event_bridge.py +899 -0
  9. {agent_pbx-2.1.0 → agent_pbx-2.2.0}/src/agent_pbx/codex/runtime.py +188 -3
  10. {agent_pbx-2.1.0 → agent_pbx-2.2.0}/src/agent_pbx/codex/state.py +6 -0
  11. {agent_pbx-2.1.0 → agent_pbx-2.2.0}/src/agent_pbx/codex_config.py +24 -0
  12. {agent_pbx-2.1.0 → agent_pbx-2.2.0}/src/agent_pbx/codex_sessions.py +81 -0
  13. agent_pbx-2.2.0/src/agent_pbx/codex_theme.py +198 -0
  14. {agent_pbx-2.1.0 → agent_pbx-2.2.0}/src/agent_pbx/config.py +5 -0
  15. agent_pbx-2.2.0/src/agent_pbx/demo/__init__.py +9 -0
  16. agent_pbx-2.2.0/src/agent_pbx/demo/contract.py +77 -0
  17. agent_pbx-2.2.0/src/agent_pbx/demo/fake_codex.py +326 -0
  18. agent_pbx-2.2.0/src/agent_pbx/demo/fake_github.py +136 -0
  19. agent_pbx-2.2.0/src/agent_pbx/demo/fake_joplin.py +169 -0
  20. agent_pbx-2.2.0/src/agent_pbx/demo/fake_workerbee.py +70 -0
  21. agent_pbx-2.2.0/src/agent_pbx/demo/fixtures.py +143 -0
  22. agent_pbx-2.2.0/src/agent_pbx/demo/policy.py +222 -0
  23. agent_pbx-2.2.0/src/agent_pbx/demo/session.py +579 -0
  24. agent_pbx-2.2.0/src/agent_pbx/demo/web.py +353 -0
  25. agent_pbx-2.2.0/src/agent_pbx/dev_harness.py +568 -0
  26. {agent_pbx-2.1.0 → agent_pbx-2.2.0}/src/agent_pbx/doctor.py +222 -5
  27. {agent_pbx-2.1.0 → agent_pbx-2.2.0}/src/agent_pbx/files.py +36 -0
  28. {agent_pbx-2.1.0 → agent_pbx-2.2.0}/src/agent_pbx/joplin.py +904 -10
  29. {agent_pbx-2.1.0 → agent_pbx-2.2.0}/src/agent_pbx/lifecycle.py +13 -13
  30. {agent_pbx-2.1.0 → agent_pbx-2.2.0}/src/agent_pbx/managed_runtime.py +84 -8
  31. {agent_pbx-2.1.0 → agent_pbx-2.2.0}/src/agent_pbx/mcp_daemon.py +299 -2
  32. {agent_pbx-2.1.0 → agent_pbx-2.2.0}/src/agent_pbx/mcp_tools.py +12 -0
  33. {agent_pbx-2.1.0 → agent_pbx-2.2.0}/src/agent_pbx/operator.py +122 -13
  34. {agent_pbx-2.1.0 → agent_pbx-2.2.0}/src/agent_pbx/runtime_tmux.py +293 -19
  35. {agent_pbx-2.1.0 → agent_pbx-2.2.0}/src/agent_pbx/schemas.py +59 -0
  36. agent_pbx-2.2.0/src/agent_pbx/setup_assistant.py +331 -0
  37. {agent_pbx-2.1.0 → agent_pbx-2.2.0}/src/agent_pbx/store.py +380 -10
  38. {agent_pbx-2.1.0 → agent_pbx-2.2.0}/src/agent_pbx/terminal/conformance.py +7 -5
  39. {agent_pbx-2.1.0 → agent_pbx-2.2.0}/src/agent_pbx/terminal/widget.py +218 -38
  40. agent_pbx-2.2.0/src/agent_pbx/terminal_editor.py +857 -0
  41. {agent_pbx-2.1.0 → agent_pbx-2.2.0}/src/agent_pbx/tmux.py +233 -48
  42. agent_pbx-2.2.0/src/agent_pbx/tmux_binary.py +188 -0
  43. {agent_pbx-2.1.0 → agent_pbx-2.2.0}/src/agent_pbx/tui.py +3604 -134
  44. {agent_pbx-2.1.0 → agent_pbx-2.2.0}/src/agent_pbx/tui_cli.py +2 -0
  45. agent_pbx-2.2.0/src/agent_pbx/ui/navigation.py +83 -0
  46. agent_pbx-2.2.0/src/agent_pbx/ui/palette_history.py +250 -0
  47. {agent_pbx-2.1.0 → agent_pbx-2.2.0}/src/agent_pbx/ui/panels/joplin.py +46 -0
  48. {agent_pbx-2.1.0 → agent_pbx-2.2.0}/src/agent_pbx/ui/theme.py +39 -16
  49. agent_pbx-2.2.0/src/agent_pbx/wiki_publish.py +397 -0
  50. {agent_pbx-2.1.0 → agent_pbx-2.2.0}/src/agent_pbx/workerbee.py +6 -0
  51. agent_pbx-2.2.0/src/agent_pbx/workerbee_harness.py +219 -0
  52. {agent_pbx-2.1.0 → agent_pbx-2.2.0}/src/agent_pbx/workerbee_mcp.py +233 -7
  53. agent_pbx-2.2.0/src/agent_pbx/workerbee_switcher.py +443 -0
  54. agent_pbx-2.1.0/README.md → agent_pbx-2.2.0/src/agent_pbx.egg-info/PKG-INFO +337 -55
  55. {agent_pbx-2.1.0 → agent_pbx-2.2.0}/src/agent_pbx.egg-info/SOURCES.txt +39 -0
  56. {agent_pbx-2.1.0 → agent_pbx-2.2.0}/src/agent_pbx.egg-info/requires.txt +4 -0
  57. {agent_pbx-2.1.0 → agent_pbx-2.2.0}/tests/test_codex_adapter.py +8 -0
  58. {agent_pbx-2.1.0 → agent_pbx-2.2.0}/tests/test_codex_config.py +31 -0
  59. agent_pbx-2.2.0/tests/test_codex_event_bridge.py +386 -0
  60. {agent_pbx-2.1.0 → agent_pbx-2.2.0}/tests/test_codex_sessions.py +39 -0
  61. agent_pbx-2.2.0/tests/test_codex_theme.py +72 -0
  62. agent_pbx-2.2.0/tests/test_dev_harness.py +164 -0
  63. agent_pbx-2.2.0/tests/test_docs.py +36 -0
  64. {agent_pbx-2.1.0 → agent_pbx-2.2.0}/tests/test_doctor.py +80 -0
  65. {agent_pbx-2.1.0 → agent_pbx-2.2.0}/tests/test_joplin.py +816 -6
  66. {agent_pbx-2.1.0 → agent_pbx-2.2.0}/tests/test_lifecycle.py +4 -1
  67. {agent_pbx-2.1.0 → agent_pbx-2.2.0}/tests/test_managed_runtime.py +67 -1
  68. {agent_pbx-2.1.0 → agent_pbx-2.2.0}/tests/test_mcp_daemon.py +171 -0
  69. {agent_pbx-2.1.0 → agent_pbx-2.2.0}/tests/test_mcp_tools.py +60 -0
  70. agent_pbx-2.2.0/tests/test_navigation.py +47 -0
  71. {agent_pbx-2.1.0 → agent_pbx-2.2.0}/tests/test_operator.py +109 -0
  72. agent_pbx-2.2.0/tests/test_palette_history.py +47 -0
  73. agent_pbx-2.2.0/tests/test_public_demo_fixtures.py +94 -0
  74. agent_pbx-2.2.0/tests/test_public_demo_policy.py +131 -0
  75. agent_pbx-2.2.0/tests/test_public_demo_session.py +94 -0
  76. agent_pbx-2.2.0/tests/test_public_demo_web.py +171 -0
  77. agent_pbx-2.2.0/tests/test_readme.py +34 -0
  78. {agent_pbx-2.1.0 → agent_pbx-2.2.0}/tests/test_release_packaging.py +17 -0
  79. agent_pbx-2.2.0/tests/test_release_validation.py +277 -0
  80. {agent_pbx-2.1.0 → agent_pbx-2.2.0}/tests/test_remote.py +1 -1
  81. {agent_pbx-2.1.0 → agent_pbx-2.2.0}/tests/test_runtime_tmux.py +378 -8
  82. {agent_pbx-2.1.0 → agent_pbx-2.2.0}/tests/test_runtime_ux.py +231 -0
  83. agent_pbx-2.2.0/tests/test_setup_assistant.py +187 -0
  84. {agent_pbx-2.1.0 → agent_pbx-2.2.0}/tests/test_store.py +120 -0
  85. {agent_pbx-2.1.0 → agent_pbx-2.2.0}/tests/test_terminal.py +87 -0
  86. agent_pbx-2.2.0/tests/test_terminal_editor.py +700 -0
  87. {agent_pbx-2.1.0 → agent_pbx-2.2.0}/tests/test_tmux.py +92 -13
  88. agent_pbx-2.2.0/tests/test_tmux_binary.py +81 -0
  89. {agent_pbx-2.1.0 → agent_pbx-2.2.0}/tests/test_tui.py +2812 -232
  90. {agent_pbx-2.1.0 → agent_pbx-2.2.0}/tests/test_ui_controllers.py +25 -0
  91. agent_pbx-2.2.0/tests/test_wiki_publish.py +153 -0
  92. agent_pbx-2.2.0/tests/test_workerbee_harness.py +169 -0
  93. agent_pbx-2.2.0/tests/test_workerbee_mcp.py +178 -0
  94. agent_pbx-2.2.0/tests/test_workerbee_switcher.py +252 -0
  95. {agent_pbx-2.1.0 → agent_pbx-2.2.0}/tests/test_workflow.py +48 -0
  96. agent_pbx-2.1.0/tests/test_workerbee_mcp.py +0 -79
  97. {agent_pbx-2.1.0 → agent_pbx-2.2.0}/LICENSE +0 -0
  98. {agent_pbx-2.1.0 → agent_pbx-2.2.0}/setup.cfg +0 -0
  99. {agent_pbx-2.1.0 → agent_pbx-2.2.0}/src/agent_pbx/__main__.py +0 -0
  100. {agent_pbx-2.1.0 → agent_pbx-2.2.0}/src/agent_pbx/agent.py +0 -0
  101. {agent_pbx-2.1.0 → agent_pbx-2.2.0}/src/agent_pbx/auth.py +0 -0
  102. {agent_pbx-2.1.0 → agent_pbx-2.2.0}/src/agent_pbx/client.py +0 -0
  103. {agent_pbx-2.1.0 → agent_pbx-2.2.0}/src/agent_pbx/codex/__init__.py +0 -0
  104. {agent_pbx-2.1.0 → agent_pbx-2.2.0}/src/agent_pbx/codex/adapter.py +0 -0
  105. {agent_pbx-2.1.0 → agent_pbx-2.2.0}/src/agent_pbx/codex/capabilities.py +0 -0
  106. {agent_pbx-2.1.0 → agent_pbx-2.2.0}/src/agent_pbx/codex/models.py +0 -0
  107. {agent_pbx-2.1.0 → agent_pbx-2.2.0}/src/agent_pbx/codex/profiles.py +0 -0
  108. {agent_pbx-2.1.0 → agent_pbx-2.2.0}/src/agent_pbx/codex/protocol.py +0 -0
  109. {agent_pbx-2.1.0 → agent_pbx-2.2.0}/src/agent_pbx/codex/sessions.py +0 -0
  110. {agent_pbx-2.1.0 → agent_pbx-2.2.0}/src/agent_pbx/codex/skills.py +0 -0
  111. {agent_pbx-2.1.0 → agent_pbx-2.2.0}/src/agent_pbx/codex_cli.py +0 -0
  112. {agent_pbx-2.1.0 → agent_pbx-2.2.0}/src/agent_pbx/compat.py +0 -0
  113. {agent_pbx-2.1.0 → agent_pbx-2.2.0}/src/agent_pbx/contracts.py +0 -0
  114. {agent_pbx-2.1.0 → agent_pbx-2.2.0}/src/agent_pbx/debug_smoke.py +0 -0
  115. {agent_pbx-2.1.0 → agent_pbx-2.2.0}/src/agent_pbx/envfile.py +0 -0
  116. {agent_pbx-2.1.0 → agent_pbx-2.2.0}/src/agent_pbx/events.py +0 -0
  117. {agent_pbx-2.1.0 → agent_pbx-2.2.0}/src/agent_pbx/issues.py +0 -0
  118. {agent_pbx-2.1.0 → agent_pbx-2.2.0}/src/agent_pbx/migration.py +0 -0
  119. {agent_pbx-2.1.0 → agent_pbx-2.2.0}/src/agent_pbx/pairing.py +0 -0
  120. {agent_pbx-2.1.0 → agent_pbx-2.2.0}/src/agent_pbx/paths.py +0 -0
  121. {agent_pbx-2.1.0 → agent_pbx-2.2.0}/src/agent_pbx/polling.py +0 -0
  122. {agent_pbx-2.1.0 → agent_pbx-2.2.0}/src/agent_pbx/project_spawn.py +0 -0
  123. {agent_pbx-2.1.0 → agent_pbx-2.2.0}/src/agent_pbx/pull_requests.py +0 -0
  124. {agent_pbx-2.1.0 → agent_pbx-2.2.0}/src/agent_pbx/remote.py +0 -0
  125. {agent_pbx-2.1.0 → agent_pbx-2.2.0}/src/agent_pbx/security.py +0 -0
  126. {agent_pbx-2.1.0 → agent_pbx-2.2.0}/src/agent_pbx/sim_agent.py +0 -0
  127. {agent_pbx-2.1.0 → agent_pbx-2.2.0}/src/agent_pbx/sim_client.py +0 -0
  128. {agent_pbx-2.1.0 → agent_pbx-2.2.0}/src/agent_pbx/skill_packs/agent-pbx-base/SKILL.md +0 -0
  129. {agent_pbx-2.1.0 → agent_pbx-2.2.0}/src/agent_pbx/skill_packs/agent-role/SKILL.md +0 -0
  130. {agent_pbx-2.1.0 → agent_pbx-2.2.0}/src/agent_pbx/skill_packs/operator-role/SKILL.md +0 -0
  131. {agent_pbx-2.1.0 → agent_pbx-2.2.0}/src/agent_pbx/skill_packs/review-role/SKILL.md +0 -0
  132. {agent_pbx-2.1.0 → agent_pbx-2.2.0}/src/agent_pbx/skill_packs/roses-architect/SKILL.md +0 -0
  133. {agent_pbx-2.1.0 → agent_pbx-2.2.0}/src/agent_pbx/terminal/__init__.py +0 -0
  134. {agent_pbx-2.1.0 → agent_pbx-2.2.0}/src/agent_pbx/terminal/keys.py +0 -0
  135. {agent_pbx-2.1.0 → agent_pbx-2.2.0}/src/agent_pbx/terminal/pty.py +0 -0
  136. {agent_pbx-2.1.0 → agent_pbx-2.2.0}/src/agent_pbx/terminal/screen.py +0 -0
  137. {agent_pbx-2.1.0 → agent_pbx-2.2.0}/src/agent_pbx/transcript.py +0 -0
  138. {agent_pbx-2.1.0 → agent_pbx-2.2.0}/src/agent_pbx/uat.py +0 -0
  139. {agent_pbx-2.1.0 → agent_pbx-2.2.0}/src/agent_pbx/ui/__init__.py +0 -0
  140. {agent_pbx-2.1.0 → agent_pbx-2.2.0}/src/agent_pbx/ui/actions.py +0 -0
  141. {agent_pbx-2.1.0 → agent_pbx-2.2.0}/src/agent_pbx/ui/async_jobs.py +0 -0
  142. {agent_pbx-2.1.0 → agent_pbx-2.2.0}/src/agent_pbx/ui/focus.py +0 -0
  143. {agent_pbx-2.1.0 → agent_pbx-2.2.0}/src/agent_pbx/ui/panels/__init__.py +0 -0
  144. {agent_pbx-2.1.0 → agent_pbx-2.2.0}/src/agent_pbx/ui/panels/editor.py +0 -0
  145. {agent_pbx-2.1.0 → agent_pbx-2.2.0}/src/agent_pbx/ui/panels/operators.py +0 -0
  146. {agent_pbx-2.1.0 → agent_pbx-2.2.0}/src/agent_pbx/ui/runtime.py +0 -0
  147. {agent_pbx-2.1.0 → agent_pbx-2.2.0}/src/agent_pbx.egg-info/dependency_links.txt +0 -0
  148. {agent_pbx-2.1.0 → agent_pbx-2.2.0}/src/agent_pbx.egg-info/entry_points.txt +0 -0
  149. {agent_pbx-2.1.0 → agent_pbx-2.2.0}/src/agent_pbx.egg-info/top_level.txt +0 -0
  150. {agent_pbx-2.1.0 → agent_pbx-2.2.0}/tests/test_agent_adoption.py +0 -0
  151. {agent_pbx-2.1.0 → agent_pbx-2.2.0}/tests/test_agent_instructions.py +0 -0
  152. {agent_pbx-2.1.0 → agent_pbx-2.2.0}/tests/test_auth_pairing.py +0 -0
  153. {agent_pbx-2.1.0 → agent_pbx-2.2.0}/tests/test_codex_cli.py +0 -0
  154. {agent_pbx-2.1.0 → agent_pbx-2.2.0}/tests/test_codex_profiles.py +0 -0
  155. {agent_pbx-2.1.0 → agent_pbx-2.2.0}/tests/test_compat.py +0 -0
  156. {agent_pbx-2.1.0 → agent_pbx-2.2.0}/tests/test_contracts.py +0 -0
  157. {agent_pbx-2.1.0 → agent_pbx-2.2.0}/tests/test_debug_smoke.py +0 -0
  158. {agent_pbx-2.1.0 → agent_pbx-2.2.0}/tests/test_demo_codex.py +0 -0
  159. {agent_pbx-2.1.0 → agent_pbx-2.2.0}/tests/test_events.py +0 -0
  160. {agent_pbx-2.1.0 → agent_pbx-2.2.0}/tests/test_health.py +0 -0
  161. {agent_pbx-2.1.0 → agent_pbx-2.2.0}/tests/test_issues.py +0 -0
  162. {agent_pbx-2.1.0 → agent_pbx-2.2.0}/tests/test_migration.py +0 -0
  163. {agent_pbx-2.1.0 → agent_pbx-2.2.0}/tests/test_polling.py +0 -0
  164. {agent_pbx-2.1.0 → agent_pbx-2.2.0}/tests/test_project_spawn.py +0 -0
  165. {agent_pbx-2.1.0 → agent_pbx-2.2.0}/tests/test_pull_requests.py +0 -0
  166. {agent_pbx-2.1.0 → agent_pbx-2.2.0}/tests/test_tui_cli.py +0 -0
  167. {agent_pbx-2.1.0 → agent_pbx-2.2.0}/tests/test_uat.py +0 -0
  168. {agent_pbx-2.1.0 → agent_pbx-2.2.0}/tests/test_workerbee.py +0 -0
@@ -1,9 +1,14 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: agent-pbx
3
- Version: 2.1.0
3
+ Version: 2.2.0
4
4
  Summary: Runtime-grounded control plane for durable Codex Agent and Operator sessions.
5
5
  Author: Agent PBX contributors
6
6
  License-Expression: Apache-2.0
7
+ Project-URL: Homepage, https://github.com/m4xx3d0ut/agent-pbx
8
+ Project-URL: Documentation, https://github.com/m4xx3d0ut/agent-pbx/wiki
9
+ Project-URL: Repository, https://github.com/m4xx3d0ut/agent-pbx
10
+ Project-URL: Issues, https://github.com/m4xx3d0ut/agent-pbx/issues
11
+ Project-URL: Changelog, https://github.com/m4xx3d0ut/agent-pbx/blob/dev/CHANGELOG.md
7
12
  Classifier: Programming Language :: Python :: 3
8
13
  Classifier: Programming Language :: Python :: 3.10
9
14
  Requires-Python: >=3.10
@@ -21,11 +26,14 @@ Requires-Dist: uvicorn[standard]<0.48,>=0.29
21
26
  Requires-Dist: websockets<17,>=14
22
27
  Provides-Extra: images
23
28
  Requires-Dist: Pillow<12,>=10; extra == "images"
29
+ Provides-Extra: web-demo
30
+ Requires-Dist: textual-serve<2,>=1.1.3; extra == "web-demo"
24
31
  Provides-Extra: dev
25
32
  Requires-Dist: build<2,>=1; extra == "dev"
26
33
  Requires-Dist: pytest<9,>=8; extra == "dev"
27
34
  Requires-Dist: pytest-asyncio<1,>=0.23; extra == "dev"
28
35
  Requires-Dist: pytest-xdist<4,>=3; extra == "dev"
36
+ Requires-Dist: twine<7,>=6; extra == "dev"
29
37
  Dynamic: license-file
30
38
 
31
39
  # Agent PBX
@@ -33,7 +41,7 @@ Dynamic: license-file
33
41
  **A runtime-grounded Agentic Engineering Control Plane.**
34
42
 
35
43
  <p align="center">
36
- <img src="docs/assets/agent-pbx-tui.gif" alt="Agent PBX v2 showing an embedded native tmux and Codex runtime, managed Agent and Operator launch, campaigns, model configuration, WorkerBee status, project workflows, and Joplin reading mode" width="1200">
44
+ <img src="https://raw.githubusercontent.com/m4xx3d0ut/agent-pbx/dev/docs/assets/agent-pbx-tui.gif" alt="Agent PBX v2 showing an embedded native tmux and Codex runtime, managed Agent and Operator launch, campaigns, model configuration, WorkerBee status, project workflows, and Joplin reading mode" width="1200">
37
45
  </p>
38
46
 
39
47
  Agent PBX gives engineering operators one durable control surface for Agents,
@@ -63,22 +71,33 @@ Operations**, or **Agentic StackOps**.
63
71
  - **Multiple control surfaces:** use the local TUI, SSH-native attachment,
64
72
  scoped remote clients, HTTP/WSS, and MCP against the same durable state.
65
73
 
66
- ```mermaid
67
- flowchart LR
68
- HUMAN[Engineering operator] --> PBX[Agent PBX control plane]
74
+ <p align="center">
75
+ <a href="https://github.com/m4xx3d0ut/agent-pbx/blob/dev/docs/diagrams/agent-pbx-control-plane.mmd">
76
+ <img src="https://raw.githubusercontent.com/m4xx3d0ut/agent-pbx/dev/docs/assets/agent-pbx-control-plane.png" alt="Agent PBX control plane connecting an engineering operator to durable Agents and Operators, policy, control surfaces, managed tmux and Codex runtimes, and optional WorkerBee runtime truth" width="1200">
77
+ </a>
78
+ </p>
79
+
80
+ The diagram's maintained [Mermaid source](https://github.com/m4xx3d0ut/agent-pbx/blob/dev/docs/diagrams/agent-pbx-control-plane.mmd)
81
+ is tracked with the repository.
69
82
 
70
- PBX --> ID[Durable Agents and Operators]
71
- PBX --> POLICY[Policy, routing, approvals, lifecycle, audit]
72
- PBX --> UI[TUI, SSH, API, WSS, MCP]
83
+ ### Interactive browser demo
73
84
 
74
- ID --> TMUX[PBX-managed tmux runtimes]
75
- TMUX --> CODEX[Codex root sessions]
76
- CODEX --> CHILDREN[Codex subagents]
85
+ The optional browser demo runs the real Agent PBX TUI against a fresh,
86
+ deterministic daemon, database, Git projects, integrations, and tmux server for
87
+ each visitor. It does not connect to workstation Agents, credentials, projects,
88
+ or runtime state.
77
89
 
78
- PBX <--> WB[WorkerBee, optional]
79
- WB <--> STACK[Application, platform, and infrastructure truth]
90
+ ```bash
91
+ python -m pip install "agent-pbx[web-demo]"
92
+ agent-pbx demo doctor
93
+ agent-pbx demo web --host 127.0.0.1 --port 8000
80
94
  ```
81
95
 
96
+ Source contributors can use `python -m pip install -e ".[web-demo]"` from a
97
+ checkout. See the [interactive browser demo guide](https://github.com/m4xx3d0ut/agent-pbx/blob/dev/docs/public-browser-demo.md) for the
98
+ rootless container, HTTPS reverse-proxy boundary, resource controls, public
99
+ origin policy, and versioned product-site contract.
100
+
82
101
  | Layer | Owns |
83
102
  |---|---|
84
103
  | Agent PBX | Durable identity, workspace ownership, topology, routing, policy, approvals, lifecycle, campaigns, handoffs, and audit |
@@ -88,9 +107,10 @@ flowchart LR
88
107
  | WorkerBee | Optional application, infrastructure, simulation, deployment, and runtime truth |
89
108
  | TUI | Operator interaction and rendering; closing it does not stop the managed runtime |
90
109
 
91
- See [the architecture overview](docs/architecture.md),
92
- [the v2.1 release notes](docs/releases/v2.1.0.md), and
93
- [the accepted architecture decisions](docs/adr/README.md) for the complete
110
+ See [the architecture overview](https://github.com/m4xx3d0ut/agent-pbx/blob/dev/docs/architecture.md),
111
+ [the project wiki](https://github.com/m4xx3d0ut/agent-pbx/wiki),
112
+ [the v2.2 release notes](https://github.com/m4xx3d0ut/agent-pbx/blob/dev/docs/releases/v2.2.0.md), and
113
+ [the accepted architecture decisions](https://github.com/m4xx3d0ut/agent-pbx/blob/dev/docs/adr/README.md) for the complete
94
114
  control-plane and compatibility boundaries.
95
115
 
96
116
  ### Why PBX?
@@ -103,6 +123,19 @@ connect through one governed exchange.
103
123
 
104
124
  ## Install
105
125
 
126
+ ### Install from PyPI
127
+
128
+ Install the current Python package in a virtual environment with:
129
+
130
+ ```bash
131
+ python -m pip install agent-pbx
132
+ agent-pbx --version
133
+ ```
134
+
135
+ PyPI contains the Agent PBX wheel and source distribution. Use the GitHub
136
+ Release wheelhouse below when a checksummed offline dependency bundle is
137
+ required.
138
+
106
139
  ### One-line release install
107
140
 
108
141
  When release artifacts are published, install the latest wheelhouse with:
@@ -184,7 +217,7 @@ the large Textual test module can be distributed by test instead of being
184
217
  pinned to one worker. Run `scripts/test_full.sh --serial` for a complete
185
218
  single-process parity check. Tests marked `serial` are excluded from all xdist
186
219
  workers and run afterward in the controller process. See
187
- [test execution and qualification](docs/testing.md) for worker-count evidence,
220
+ [test execution and qualification](https://github.com/m4xx3d0ut/agent-pbx/blob/dev/docs/testing.md) for worker-count evidence,
188
221
  resource-isolation rules, and failure reproduction.
189
222
 
190
223
  The server defaults to localhost. LAN binding requires bearer authentication,
@@ -193,9 +226,13 @@ controller roles, audience and expiry, optional client/Agent binding, immediate
193
226
  revocation, and audit. Agent-scoped controllers cannot use global legacy API,
194
227
  credential-administration, audit, or MCP surfaces.
195
228
 
196
- See [v2 installation and upgrade](docs/install-v2.md) for Linux/macOS host
229
+ See [v2 installation and upgrade](https://github.com/m4xx3d0ut/agent-pbx/blob/dev/docs/install-v2.md) for Linux/macOS host
197
230
  requirements, remote clients, verified/offline wheelhouses, migration, and
198
- rollback.
231
+ rollback. Maintainers should follow the
232
+ [Trusted Publishing release procedure](https://github.com/m4xx3d0ut/agent-pbx/blob/dev/docs/releasing.md) for TestPyPI and
233
+ production PyPI releases. Repository documentation and wiki source can be
234
+ checked without touching services by running `python scripts/check_docs.py`
235
+ and `agent-pbx wiki check --source docs/wiki`.
199
236
 
200
237
  ## Local Environment
201
238
 
@@ -247,7 +284,7 @@ export AGENT_PBX_TUI_EVENT_STREAM_V2=1
247
284
  agent-pbx remote ssh-attach --host user@pbx-host --entity agent-id --read-only
248
285
  ```
249
286
 
250
- See [Checkpoint 14 remote access](docs/migrations/v2-checkpoint-14-remote.md)
287
+ See [Checkpoint 14 remote access](https://github.com/m4xx3d0ut/agent-pbx/blob/dev/docs/migrations/v2-checkpoint-14-remote.md)
251
288
  for the credential, TLS, revocation, snapshot, and rollback model.
252
289
 
253
290
  For the common local workflow:
@@ -694,11 +731,13 @@ delivery.
694
731
  ## WorkerBee TUI Status
695
732
 
696
733
  Set `AGENT_PBX_WORKERBEE_BIN` before starting the Agent PBX daemon to enable
697
- the read-only WorkerBee tab in the TUI. The daemon runs WorkerBee status
698
- commands; the TUI only renders the API result.
734
+ the WorkerBee status tab in the TUI. The daemon runs WorkerBee status
735
+ commands; the TUI only renders the API result. When a versioned backend status
736
+ helper is configured, doctor and the tab also show backend provenance, endpoint
737
+ alignment, server identity, and PBX-host versus WorkerBee-visible project paths.
699
738
 
700
739
  ```bash
701
- export AGENT_PBX_WORKERBEE_BIN=/home/m4xx3d0ut/git/k1s-wt/k1s-workerbee/.venv/bin/workerbee
740
+ export AGENT_PBX_WORKERBEE_BIN="$HOME/git/k1s-workerbee/.venv/bin/workerbee"
702
741
  export AGENT_PBX_WORKERBEE_TIMEOUT_SECONDS=20
703
742
  agent-pbx mcp restart --token dev-token
704
743
  agent-pbx tui --token dev-token
@@ -707,13 +746,36 @@ agent-pbx tui --token dev-token
707
746
  Agents must register with `metadata.cwd` set to their project directory. When
708
747
  the selected agent is in a WorkerBee project, the tab shows the WorkerBee
709
748
  project name, mode, running state, dashboard URLs, app readiness, latest
710
- deployment metadata, ingress URLs, workloads, and validation findings. The v1
711
- tab does not start, stop, deploy, or mutate WorkerBee projects.
749
+ deployment metadata, ingress URLs, workloads, and validation findings. These
750
+ project-status views do not start, stop, deploy, or mutate WorkerBee projects.
712
751
  `AGENT_PBX_WORKERBEE_TIMEOUT_SECONDS` defaults to `20` because `workerbee
713
752
  projects` can take more than ten seconds on hosts with many projects. Agent PBX
714
753
  also serializes same-agent WorkerBee checks and caches results briefly to avoid
715
754
  WorkerBee project-lock collisions from repeated refreshes.
716
755
 
756
+ A valid PBX project reported missing by WorkerBee is treated as a path-
757
+ visibility diagnostic rather than evidence that the WorkerBee server needs a
758
+ patch. Omitted launch tools, unavailable endpoints, older servers, and path
759
+ mismatches produce distinct diagnostics. See the
760
+ [WorkerBee wiki guide](https://github.com/m4xx3d0ut/agent-pbx/wiki/WorkerBee-Integration).
761
+
762
+ When both versioned switch helpers are configured, the WorkerBee tab and
763
+ palette can preview a change between OSS and platform-debug MCP backends:
764
+
765
+ ```bash
766
+ export AGENT_PBX_WORKERBEE_SWITCHER_STATUS_BIN="$HOME/.local/bin/wb-mcp-status"
767
+ export AGENT_PBX_WORKERBEE_SWITCHER_BIN="$HOME/.local/bin/wb-mcp-switch"
768
+ ```
769
+
770
+ `/workerbee switch oss` and `/workerbee switch debug` always begin with the
771
+ switcher's real non-mutating `--dry-run` result. Apply requires an unexpired
772
+ private transaction, unchanged backend evidence, exact typed confirmation, and
773
+ an additional privileged confirmation for platform-debug. Agent PBX verifies
774
+ both backend provenance and WorkerBee MCP capabilities after apply, attempts
775
+ automatic restoration on failure, and provides `/workerbee switch rollback`
776
+ for the last verified transaction. The change applies only to future sessions;
777
+ running Codex sessions remain pinned to their existing MCP binding.
778
+
717
779
  ## Pull Request Review
718
780
 
719
781
  Set `AGENT_PBX_PR_ENABLED=1` before starting the daemon to enable the `PRs` tab
@@ -823,24 +885,58 @@ through Agent PBX, waits for the tmux pane to settle, then asks Codex for
823
885
  previews Markdown, and supports quick create, rename, delete, and save controls
824
886
  inside the Agent PBX notebook scope only.
825
887
 
826
- The Joplin tab status line shows queued, running, successful, and failed sync
827
- state. Press `Sync Now` or use `/joplin sync` to queue a manual sync. Sync
828
- failures are retained in Agent PBX status/events; they do not roll back the note
829
- write that triggered them.
888
+ The project folder name comes from the caller's route-safe logical Agent PBX
889
+ project identity; its absolute `metadata.cwd` remains separate and cannot
890
+ replace that identity during a report refresh. Note list/get requests never
891
+ create missing project or Agent folders. Folder creation occurs only for an
892
+ explicit note-creation operation.
893
+
894
+ The Joplin tab reports targeted write health separately from whole-profile E2EE
895
+ validation, for example `Writes: ok | Profile: E2EE locked 17`. Press
896
+ `Validate` or use `/joplin validate profile` to run the strict whole-profile
897
+ check. `/joplin sync` remains a compatibility alias. Historical failures remain
898
+ in Agent PBX status/events for audit; they do not roll back a note write that
899
+ completed successfully.
900
+
901
+ Encrypted items are shown as `🔒 decryption pending`, never as empty notes.
902
+ Agent PBX does not return encrypted payloads through its API and blocks edit,
903
+ rename, delete, append, and overwrite actions until the configured Joplin
904
+ profile decrypts the item. A targeted write succeeds after its declared note is
905
+ verified as plaintext even when unrelated encrypted objects remain. Strict
906
+ profile validation requires zero pending encrypted notes, resources, and
907
+ folders; otherwise that validation job fails with `JOPLIN_E2EE_LOCKED` and the
908
+ status line shows the pending count.
909
+
910
+ Joplin-native conflict copies are shown as `⚠ LOCAL` and kept read-only
911
+ because they are local recovery records without normal remote sync items. Use
912
+ `Promote Local` twice within five seconds, or `/joplin promote conflict`, to
913
+ create a revision-checked, uniquely titled normal note containing the same
914
+ Markdown. Agent PBX preserves the readable conflict and its encrypted original;
915
+ the promoted copy follows the regular targeted-sync path without requiring a
916
+ whole-profile E2EE decrypt pass.
830
917
 
831
918
  Joplin actions are available from the tab buttons and the local TUI
832
919
  palette/slash commands: `/joplin` opens the tab, `/joplin refresh` reloads
833
920
  scoped notes, `/joplin new` creates a scoped note, `/joplin rename` renames the
834
921
  selected note, `/joplin delete` confirms and deletes the selected scoped note,
922
+ `/joplin promote conflict` safely promotes a selected local conflict copy,
835
923
  `/joplin copy` copies the latest Codex response in tmux direct mode, `/joplin
836
924
  copy report` copies the latest PBX report, `/joplin log start` and `/joplin log
837
925
  stop` control the growing LOG note, `/joplin save` saves the selected note body,
838
- and `/joplin sync` queues a manual sync job.
926
+ and `/joplin validate profile` queues a strict profile validation. `/joplin
927
+ sync` is retained as an alias for the same strict operation.
839
928
 
840
929
  The Joplin tab buttons show their shortcut key directly, such as `New n` and
841
930
  `Copy c`. Press `Ctrl+G` then that key; when focus is outside an editable note
842
931
  body, `j` can be used instead of `Ctrl+G`.
843
932
 
933
+ The rendered reading view is keyboard-focusable and keeps a revision-scoped
934
+ position for each note and preview. Arrow keys and Page Up/Page Down therefore
935
+ work over desktop, SSH, and Termux without unchanged refreshes snapping back to
936
+ the top. Explicit Copy actions can copy selected Markdown or the whole note.
937
+ Paste is edit-only, revalidates the selected note revision, and confirms large
938
+ or multiline clipboard payloads using metadata rather than echoing their text.
939
+
844
940
  In tmux direct mode, `/joplin copy` first reads the active Codex transcript when
845
941
  Agent PBX knows the session id. If transcript capture is unavailable, it uses
846
942
  Codex `/copy` and a local clipboard helper such as `wl-paste`, `xclip`, `xsel`,
@@ -869,6 +965,41 @@ joplin --profile ~/.config/joplin-agent-pbx
869
965
  # Inside Joplin: :server start
870
966
  ```
871
967
 
968
+ Joplin documents the terminal Data API server and terminal sync client as
969
+ separate profile users. They must not operate the same profile concurrently.
970
+ The safe committed default is:
971
+
972
+ ```bash
973
+ AGENT_PBX_JOPLIN_PROFILE_OWNER_MODE=external
974
+ ```
975
+
976
+ In `external` mode, Agent PBX refuses CLI sync while a validated same-profile
977
+ Data API server is running. A dedicated single-user workstation may opt into:
978
+
979
+ ```bash
980
+ AGENT_PBX_JOPLIN_PROFILE_OWNER_MODE=managed_cli
981
+ ```
982
+
983
+ With an explicit `AGENT_PBX_JOPLIN_PROFILE`, Agent PBX verifies the profile
984
+ server PID, process owner, executable, and command; stops that exact server;
985
+ runs one profile-locked sync and restarts the Data API server. Targeted writes
986
+ then verify only their declared note and do not invoke whole-profile decryption.
987
+ Strict profile validation additionally runs a non-interactive E2EE decrypt retry
988
+ before restoring the server and fails when decryption cannot complete. Agent PBX
989
+ never stops an ambiguous or foreign process. Unrelated encrypted items remain
990
+ visible as a separate profile-health warning without failing a verified targeted
991
+ write.
992
+
993
+ The managed decrypt pass uses only Joplin's own cached master-key credential.
994
+ Agent PBX does not receive or persist the E2EE password. If the credential is
995
+ missing or Joplin's crypto worker fails, the validated API server is restored
996
+ and the sync reports `JOPLIN_E2EE_PASSWORD_REQUIRED` or
997
+ `JOPLIN_E2EE_DECRYPT_FAILED`. Unlock the dedicated profile interactively before
998
+ retrying. If the master key already loads but the crypto worker still fails,
999
+ use a supported Joplin client/runtime that can decrypt the item and keep its
1000
+ encrypted payload intact until recovery succeeds. Do not put the password in
1001
+ `local.env` or a command-line argument.
1002
+
872
1003
  For E2EE troubleshooting from a shell:
873
1004
 
874
1005
  ```bash
@@ -909,14 +1040,55 @@ results can be selected to preview a match. `Copy Path` copies the selected
909
1040
  project-relative path, and `Copy Text` copies the full bounded text document for
910
1041
  the selected file through the same guarded API.
911
1042
 
912
- `Open Editor` opens the selected file or search result in the native `Editor`
913
- tab. The editor is a Textual text buffer with syntax highlighting when Textual
914
- has a language parser available. Buffers are cached per agent, so unsaved edits
915
- survive moving between tabs and selected agents during the TUI session. `Save`
916
- writes UTF-8 through an optimistic lock using the loaded file hash or mtime and
917
- reports a write conflict if the file changed on disk. `Revert` reloads the file
918
- from the daemon. `F9` or `Full F9` toggles an editor-fullscreen layout that keeps
919
- the TUI title and footer visible.
1043
+ The Files tab provides `Open Default`, `Open Text`, and `Open Native`. `Open
1044
+ Default` follows `AGENT_PBX_EDITOR_DEFAULT_SURFACE`; the committed fallback is
1045
+ `textual`. `Open Text` always loads the guarded Textual editor, while `Open
1046
+ Native` routes the selected file directly into the managed terminal editor.
1047
+
1048
+ The Textual editor provides syntax highlighting when Textual has a language
1049
+ parser available. Buffers are cached per Agent or Operator, so unsaved edits
1050
+ survive moving between tabs during the TUI session. `Save` writes UTF-8 through
1051
+ an optimistic lock using the loaded file hash or mtime and reports a conflict if
1052
+ the file changed on disk. Returning from Neovim to a clean Textual buffer
1053
+ refetches the file, so native-editor writes do not leave a stale editable copy.
1054
+ A dirty Textual buffer must be saved or reverted before its project can open in
1055
+ the native editor. `F9` or `Full F9` toggles an editor-fullscreen layout that
1056
+ keeps the TUI title and footer visible.
1057
+
1058
+ `Native` or `/editor terminal` starts or attaches a project-rooted managed
1059
+ editor without requiring a file to be staged in Textual. `/editor workspace`
1060
+ uses the configured default surface. When terminal is the configured default,
1061
+ selecting the Editor tab or running `/editor workspace` lazily opens that empty
1062
+ project workspace. Agent PBX discovers Neovim, Vim, and Nano, or reads
1063
+ allowlisted structured argument profiles from
1064
+ `AGENT_PBX_TERMINAL_EDITOR_PROFILES`. `workspace_argv` defines the fileless
1065
+ startup command; older profiles derive a compatible prefix before `{line}` or
1066
+ `{path}`. Agent PBX executes argv directly without a shell.
1067
+
1068
+ Neovim runtimes use a private RPC socket. Files selected through `Open Native`
1069
+ or `/editor terminal open` use `tab drop`: the initial empty buffer receives the
1070
+ first file, a new file opens in another tab, and a file already visible is
1071
+ reused without disturbing other buffers or tabs. Paths still pass the same
1072
+ project-root, sensitive-name, symlink, traversal, and regular-file checks as the
1073
+ Textual editor. Review-readonly sessions may open a managed editor only when
1074
+ their registered cwd is the explicit writable `metadata.work_root`.
1075
+
1076
+ Each editor runs on its own editor-only tmux server and cannot attach to, move,
1077
+ stop, or reuse a Codex runtime pane. `/editor terminal close` stops only that
1078
+ editor. Editor identity is stored in SQLite and validated against its tmux
1079
+ socket, pane, PID/start time, project root, and RPC socket after daemon or TUI
1080
+ restart. The default daemon shutdown policy is `detach`; set it to `stop` when
1081
+ daemon shutdown should end editor runtimes. If identity validation marks a saved
1082
+ mapping stale, `/editor terminal forget` removes the record only after the
1083
+ daemon proves the recorded editor is no longer live; it never kills an
1084
+ unverified process.
1085
+
1086
+ ```bash
1087
+ export AGENT_PBX_EDITOR_DEFAULT_SURFACE="terminal"
1088
+ export AGENT_PBX_TERMINAL_EDITOR_PROFILES='{"nvim":{"label":"Neovim","argv":["nvim","+{line}","--","{path}"],"workspace_argv":["nvim"]}}'
1089
+ export AGENT_PBX_TERMINAL_EDITOR_DEFAULT="nvim"
1090
+ export AGENT_PBX_TERMINAL_EDITOR_SHUTDOWN_POLICY="detach"
1091
+ ```
920
1092
 
921
1093
  `Check` runs best-effort diagnostics for the editor file through the daemon.
922
1094
  Agent PBX currently supports `ruff` and `mypy` when installed on the daemon host;
@@ -924,10 +1096,12 @@ Agent PBX currently supports `ruff` and `mypy` when installed on the daemon host
924
1096
  unavailable result when neither is present. Diagnostics are bounded by timeout
925
1097
  and remain scoped to the selected agent's registered cwd.
926
1098
 
927
- The Latest input can complete project paths with `@`. Type a project-relative
928
- reference such as `@README` or `@src/ag` and press `Tab`; Agent PBX loads the
929
- needed project directory before completing. The same completion works in tmux
930
- direct input.
1099
+ The Agent PBX prompt composer can complete project paths with `@`. Type a
1100
+ project-relative reference such as `@README` or `@src/ag` and press `Tab`;
1101
+ Agent PBX loads the needed project directory before completing. In native tmux
1102
+ mode, the embedded Codex terminal remains transparent and Codex owns raw `@`
1103
+ input. Open `Ctrl+P`, choose `/joplin prompt`, and compose there when PBX must
1104
+ expand a scoped reference before sending it to Codex.
931
1105
 
932
1106
  Joplin project notes can be referenced with `@joplin:`. Type
933
1107
  `@joplin:Release` and press `Tab` to complete project note titles; if the
@@ -938,6 +1112,9 @@ fresh and appends a `Joplin Note References` Markdown section to the prompt, so
938
1112
  gives Codex both note bodies in one message. If a referenced note cannot be
939
1113
  resolved inside the selected project scope, the prompt is not sent. Reference
940
1114
  tokens are exact note slugs; use `Tab` completion when title wording is unclear.
1115
+ With a native Codex pane focused, use `Ctrl+P` → `/joplin prompt`; typing
1116
+ `@joplin:` directly into Codex invokes Codex's own `@` behavior and is not
1117
+ intercepted by Agent PBX.
941
1118
 
942
1119
  Operator prompts can reference caller agents with `@caller:`. Select an
943
1120
  operator agent, type `@caller:project` or `@caller:Backend`, and press `Tab` to
@@ -1094,25 +1271,35 @@ commands such as `/detail`, `/ping`, `/esc`, `/ctrlc`, `/restart`, `/tmux`,
1094
1271
  `/joplin rename`, `/joplin delete`, `/joplin copy`,
1095
1272
  `/joplin copy report`, `/agents prune`, `/agents prune apply`,
1096
1273
  `/agents prune stale`, `/agents prune forks`, `/agents prune undo`,
1097
- `/show hidden agents`, `/unhide agent`, `/theme minimal`, and
1098
- `/layout compact`.
1274
+ `/show hidden agents`, `/unhide agent`, `/palette history`,
1275
+ `/palette history clear`, `/navigation back`, `/navigation forward`,
1276
+ `/editor terminal`, `/editor terminal close`, `/editor terminal forget`,
1277
+ `/workerbee switch oss`, `/workerbee switch debug`,
1278
+ `/workerbee switch rollback`,
1279
+ `/theme minimal`, and `/layout compact`.
1099
1280
  `/cancel` marks a stale or abandoned session canceled in PBX; it does not send
1100
1281
  an Escape key. Use `/esc` when you need a real Escape key event. In tmux direct
1101
1282
  mode, `/esc` sends `tmux send-keys Escape` to the selected Codex pane. Outside
1102
1283
  tmux direct mode, it queues a `send_key` command with `key="escape"` for
1103
1284
  nohup-mode agents that poll PBX. Use `/ctrlc` in tmux direct mode to send
1104
1285
  `tmux send-keys C-c` to the selected Codex pane, for example to back out of a
1105
- `/side` chat. Use `/restart` or `/codex restart` in tmux direct mode to send
1106
- Codex `/q`, wait briefly for the pane to exit, then relaunch Codex with the
1107
- known session when Agent PBX can recover the session metadata. Use `/codex
1108
- update` to ask the Agent PBX daemon to run the allowlisted npm update for
1286
+ `/side` chat. Use `/restart` or `/codex restart` in tmux direct mode to type
1287
+ Codex `/quit`, wait briefly for Codex to exit (the containing shell may remain),
1288
+ then relaunch the known Codex session when Agent PBX can recover its metadata.
1289
+ If the retained Agent or Operator has no ready v2 runtime mapping, the same
1290
+ explicit restart creates a fresh pane on the configured managed tmux server,
1291
+ resumes the preserved Codex session, registers and verifies the new mapping,
1292
+ and leaves the stale or absent pane reference behind. Agent PBX refuses to
1293
+ create a pane when the daemon cannot verify mapping state, preventing an
1294
+ unreachable runtime from being duplicated. Use `/codex update` to ask the Agent
1295
+ PBX daemon to run the allowlisted npm update for
1109
1296
  `@openai/codex`, then use `/restart` or `/codex restart` to move long-lived
1110
1297
  caller, root-operator, and fork panes onto the updated executable. TUI-owned
1111
1298
  operators and forks can be relaunched automatically; caller panes require a known
1112
1299
  Codex session id and restart through the current configured shell `codex` command
1113
1300
  when no pinned command is stored.
1114
1301
 
1115
- In the Latest input, type `/` and press `Tab` to complete slash commands inline,
1302
+ In the Agent PBX prompt composer, type `/` and press `Tab` to complete slash commands inline,
1116
1303
  or type `@` and press `Tab` to complete project paths. Type `@joplin:` and
1117
1304
  press `Tab` to complete project-scoped Joplin note titles from cache, with lazy
1118
1305
  loading on first use. In operator prompts, `@joplin:` completion uses the
@@ -1124,6 +1311,10 @@ operator is selected to complete caller agent references. Repeated `Tab` cycles
1124
1311
  matches; exact local commands such as `/esc` or `/theme minimal` execute
1125
1312
  locally on `Enter` instead of being sent to the agent.
1126
1313
 
1314
+ When `Latest` contains the native embedded Codex terminal, open the PBX command
1315
+ palette with `Ctrl+P` and choose `/joplin prompt` for `@joplin:` completion and
1316
+ expansion. Raw `/` and `@` typed in the terminal remain native Codex input.
1317
+
1127
1318
  Use `/plan` to toggle Codex plan mode for the selected agent. In tmux direct
1128
1319
  mode, Agent PBX types `/plan` with tmux key events so Codex handles it as an
1129
1320
  interactive slash command; outside tmux mode, it queues the same `send_input`
@@ -1182,10 +1373,19 @@ palette names win over custom names, and duplicate custom names are skipped.
1182
1373
  `{arg}` is the only supported placeholder; commands that use it open a small
1183
1374
  input prompt before sending.
1184
1375
 
1376
+ The palette keeps a bounded, deduplicated history of selected command names.
1377
+ Up and Down traverse that history only while the palette input owns focus.
1378
+ Prompt bodies and command arguments are never recorded, sensitive command
1379
+ classes are excluded, and persistence is off by default. Use `/palette history`
1380
+ to inspect it, `/palette history clear` to erase it, and `/palette history
1381
+ persistence on|off` to control private local persistence.
1382
+
1185
1383
  ### Custom Theme Creation Guide
1186
1384
 
1187
- Agent PBX ships with `cyberpunk`, `minimal`, and the bundled custom `1337`
1188
- theme. To create your own theme, rename the custom theme, select it, then
1385
+ Agent PBX ships with the original `cyberpunk`, the opt-in deuteranopia-friendly
1386
+ `cyberpunk-accessible` with visibly distinct deep-teal surfaces and stronger
1387
+ foreground contrast, `minimal`, and the bundled custom `1337` theme. To create
1388
+ your own theme, rename the custom theme, select it, then
1189
1389
  override the color slots with environment variables. Keep personal palettes in
1190
1390
  your gitignored `local.env` or shell profile.
1191
1391
 
@@ -1214,6 +1414,23 @@ Use `FOREGROUND` and `BACKGROUND` for normal text and the terminal base.
1214
1414
  `Settings -> Theme` or `/theme <name>` from the palette to switch back to your
1215
1415
  custom theme if another theme is selected.
1216
1416
 
1417
+ The Agent PBX frame theme and the Codex code/diff syntax theme are separate
1418
+ surfaces. Install and select the managed Codex theme with:
1419
+
1420
+ ```bash
1421
+ agent-pbx codex theme install
1422
+ agent-pbx codex theme status
1423
+ ```
1424
+
1425
+ The installer writes `agent-pbx-1337.tmTheme` under `$CODEX_HOME/themes`,
1426
+ updates only `tui.theme` in Codex configuration, creates a configuration backup
1427
+ when one already exists, and refuses to overwrite a drifted or unsafe theme
1428
+ file unless `--force` is explicitly supplied after review. Existing Codex
1429
+ processes must be restarted/resumed at a safe turn boundary before a corrected
1430
+ process environment and startup theme are guaranteed to take effect. `doctor`
1431
+ reports both managed-theme posture and a stale `NO_COLOR` retained by the
1432
+ dedicated runtime tmux server.
1433
+
1217
1434
  ### Managed Workspace Launch
1218
1435
 
1219
1436
  The v2 project picker discovers Git repositories beneath daemon-approved roots.
@@ -1237,7 +1454,7 @@ loopback daemon and `tmux` is available. `Latest` embeds a PTY-backed normal
1237
1454
  tmux client attached to the selected PBX-managed runtime. Codex keeps its native
1238
1455
  selectors, warning view, approvals, paste, mouse, resize, cursor state, and tmux
1239
1456
  scrollback. The captured pane renderer and separate input remain available as a
1240
- compatibility fallback in Agent PBX 2.1.0. Legacy-path removal still requires
1457
+ compatibility fallback in Agent PBX 2.2.0. Legacy-path removal still requires
1241
1458
  measured parity, a supported migration path, and published notice.
1242
1459
 
1243
1460
  The committed runtime-server default is `dedicated`, which works whether or not
@@ -1248,6 +1465,16 @@ workstation config to reuse a validated outer tmux server and enable targeted
1248
1465
  recursive attachment to the PBX TUI session, namespaces managed sessions, and
1249
1466
  targets only the initiating client.
1250
1467
 
1468
+ Set `AGENT_PBX_TMUX_BIN` to an absolute executable path when Agent PBX should
1469
+ use a qualified tmux build without replacing the host package. The daemon,
1470
+ TUI, embedded clients, managed launches, reconciliation, and doctor use the
1471
+ same selection. Runtime mappings record the binary that created them so a
1472
+ legacy server can retain its matching client during a staged migration.
1473
+ Set `AGENT_PBX_TMUX_RUNTIME_SOCKET` to an absolute user-owned socket path when
1474
+ separate Agent PBX installations or qualified tmux versions must use distinct
1475
+ failure domains. The default remains the user-local
1476
+ `$XDG_RUNTIME_DIR/agent-pbx/runtime-tmux.sock`.
1477
+
1251
1478
  `AGENT_PBX_TUI_TMUX=1` and `AGENT_PBX_TUI_EMBEDDED_TERMINAL_V2=1` explicitly
1252
1479
  enable the native local path. Press `Ctrl+T` from `Latest` to toggle it
1253
1480
  for the selected entity. Tmux controls are disabled when tmux is unavailable or
@@ -1255,14 +1482,26 @@ the API URL is remote. Use `agent-pbx remote ssh-attach` for full-fidelity remot
1255
1482
  terminal access; the WSS client is the observer/control path.
1256
1483
 
1257
1484
  Plain configured function keys remain global PBX navigation even under terminal
1258
- focus: `F1` Agents, `F2` Events, `F3` view, `F4` input, `F6/F7` fork navigation,
1259
- `F8` next alert, `F9` editor, and `F10` workspace launch. Repeated F8 presses
1485
+ focus: `F1` Agents, `F2` Events, `F3` view, `F4` input, `F5` Operators,
1486
+ `F6/F7` fork navigation, `F8` next alert, `F9` editor, `F10` workspace launch,
1487
+ and `F11/F12` navigation back/forward. Repeated F8 presses
1260
1488
  focus and acknowledge one displayed Agent/Operator alert at a time.
1261
1489
  Shift+F1–F12 is translated to unmodified child F1–F12. Thus F2
1262
1490
  always focuses Events while Shift+F2 opens Codex warnings. The input layer also
1263
1491
  recognizes xterm F13–F24 aliases, and the key probe documents terminal-specific
1264
1492
  SSH or Termux sequences.
1265
1493
 
1494
+ After F3 focuses the right-side tab row, Shift+F1–F11 select the stable Latest,
1495
+ Codex, Thread, Files, Editor, WorkerBee, PRs, Issues, Campaigns, KB, and Joplin
1496
+ destinations. `1..9`, `0`, and `-` provide a portable fallback while the tab row
1497
+ has focus. These shortcuts are focus-scoped: under Codex or Neovim focus,
1498
+ Shift+F keys continue to reach the child terminal.
1499
+
1500
+ F11/F12 history is private to each TUI process and records stable entity/tab
1501
+ identities, not row positions. It skips hidden, deleted, or unavailable
1502
+ destinations safely. `/navigation back` and `/navigation forward` expose the
1503
+ same traversal from the palette.
1504
+
1266
1505
  Managed sessions pin Enter to submit and `Ctrl+J` to editor newline. The
1267
1506
  embedded terminal normalizes Shift+Enter, Alt+Enter, and Ctrl+Enter to that
1268
1507
  portable newline when the client reports those combinations distinctly. Use
@@ -1284,6 +1523,16 @@ confirmed on that host. `AGENT_PBX_COMPAT_POLLING` and
1284
1523
  `AGENT_PBX_TUI_COMPAT_THREAD` independently gate the other retained v2.0 paths.
1285
1524
  Doctor and `/healthz` report this compatibility posture.
1286
1525
 
1526
+ The daemon's read-only Codex event bridge associates structured subagent
1527
+ threads and recent lifecycle items with the exact Codex thread already bound to
1528
+ an Agent or Operator. The right-side runtime tree above `Latest` then shows the
1529
+ bounded child lifecycle beneath that owner. It remains hidden until capability
1530
+ is observed and excludes child prompts, paths, hidden reasoning, tool content,
1531
+ and path-derived roles. `AGENT_PBX_CODEX_EVENT_BRIDGE=0` disables the bridge;
1532
+ `AGENT_PBX_CODEX_EVENT_BRIDGE_TRANSPORT=sidecar` bypasses shared-daemon
1533
+ probing. Qualification evidence is recorded in
1534
+ [the v2.1.2 subagent activity note](https://github.com/m4xx3d0ut/agent-pbx/blob/dev/docs/acceptance/v2.1.2-subagent-activity.md).
1535
+
1287
1536
  On tiny terminals the existing compact controls remain available. Android
1288
1537
  Termux can emit F8 with `Volume Up+8`; terminals that cannot distinguish shifted
1289
1538
  function keys can use the configured PBX leader fallback. Touch focus debugging
@@ -1304,8 +1553,11 @@ The default TUI theme uses a cyberpunk palette with neon cyan, magenta, yellow,
1304
1553
  and green over a dark terminal base. Use the `Theme` selector in `Settings` or
1305
1554
  set `AGENT_PBX_TUI_THEME` to choose another built-in theme. `minimal` uses a
1306
1555
  plain black/white terminal base while preserving semantic highlight colors for
1307
- alerts, status, and activity. `1337` keeps the black and bright-green terminal
1308
- look. See the custom theme guide above for user-defined palettes.
1556
+ alerts, status, and activity. `cyberpunk-accessible` uses a deep-teal surface
1557
+ stack and high-contrast cool status colors so it remains visibly different
1558
+ from the original navy/purple `cyberpunk` theme. `1337` keeps the black and
1559
+ bright-green terminal look. See the custom theme guide above for user-defined
1560
+ palettes.
1309
1561
 
1310
1562
  ## TUI History Thread
1311
1563