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.
- {agent_pbx-2.1.0 → agent_pbx-2.2.0}/PKG-INFO +308 -56
- agent_pbx-2.1.0/src/agent_pbx.egg-info/PKG-INFO → agent_pbx-2.2.0/README.md +299 -85
- {agent_pbx-2.1.0 → agent_pbx-2.2.0}/pyproject.toml +12 -0
- {agent_pbx-2.1.0 → agent_pbx-2.2.0}/src/agent_pbx/__init__.py +1 -1
- {agent_pbx-2.1.0 → agent_pbx-2.2.0}/src/agent_pbx/agent_adoption.py +10 -3
- {agent_pbx-2.1.0 → agent_pbx-2.2.0}/src/agent_pbx/api.py +419 -51
- {agent_pbx-2.1.0 → agent_pbx-2.2.0}/src/agent_pbx/cli.py +453 -0
- agent_pbx-2.2.0/src/agent_pbx/codex/event_bridge.py +899 -0
- {agent_pbx-2.1.0 → agent_pbx-2.2.0}/src/agent_pbx/codex/runtime.py +188 -3
- {agent_pbx-2.1.0 → agent_pbx-2.2.0}/src/agent_pbx/codex/state.py +6 -0
- {agent_pbx-2.1.0 → agent_pbx-2.2.0}/src/agent_pbx/codex_config.py +24 -0
- {agent_pbx-2.1.0 → agent_pbx-2.2.0}/src/agent_pbx/codex_sessions.py +81 -0
- agent_pbx-2.2.0/src/agent_pbx/codex_theme.py +198 -0
- {agent_pbx-2.1.0 → agent_pbx-2.2.0}/src/agent_pbx/config.py +5 -0
- agent_pbx-2.2.0/src/agent_pbx/demo/__init__.py +9 -0
- agent_pbx-2.2.0/src/agent_pbx/demo/contract.py +77 -0
- agent_pbx-2.2.0/src/agent_pbx/demo/fake_codex.py +326 -0
- agent_pbx-2.2.0/src/agent_pbx/demo/fake_github.py +136 -0
- agent_pbx-2.2.0/src/agent_pbx/demo/fake_joplin.py +169 -0
- agent_pbx-2.2.0/src/agent_pbx/demo/fake_workerbee.py +70 -0
- agent_pbx-2.2.0/src/agent_pbx/demo/fixtures.py +143 -0
- agent_pbx-2.2.0/src/agent_pbx/demo/policy.py +222 -0
- agent_pbx-2.2.0/src/agent_pbx/demo/session.py +579 -0
- agent_pbx-2.2.0/src/agent_pbx/demo/web.py +353 -0
- agent_pbx-2.2.0/src/agent_pbx/dev_harness.py +568 -0
- {agent_pbx-2.1.0 → agent_pbx-2.2.0}/src/agent_pbx/doctor.py +222 -5
- {agent_pbx-2.1.0 → agent_pbx-2.2.0}/src/agent_pbx/files.py +36 -0
- {agent_pbx-2.1.0 → agent_pbx-2.2.0}/src/agent_pbx/joplin.py +904 -10
- {agent_pbx-2.1.0 → agent_pbx-2.2.0}/src/agent_pbx/lifecycle.py +13 -13
- {agent_pbx-2.1.0 → agent_pbx-2.2.0}/src/agent_pbx/managed_runtime.py +84 -8
- {agent_pbx-2.1.0 → agent_pbx-2.2.0}/src/agent_pbx/mcp_daemon.py +299 -2
- {agent_pbx-2.1.0 → agent_pbx-2.2.0}/src/agent_pbx/mcp_tools.py +12 -0
- {agent_pbx-2.1.0 → agent_pbx-2.2.0}/src/agent_pbx/operator.py +122 -13
- {agent_pbx-2.1.0 → agent_pbx-2.2.0}/src/agent_pbx/runtime_tmux.py +293 -19
- {agent_pbx-2.1.0 → agent_pbx-2.2.0}/src/agent_pbx/schemas.py +59 -0
- agent_pbx-2.2.0/src/agent_pbx/setup_assistant.py +331 -0
- {agent_pbx-2.1.0 → agent_pbx-2.2.0}/src/agent_pbx/store.py +380 -10
- {agent_pbx-2.1.0 → agent_pbx-2.2.0}/src/agent_pbx/terminal/conformance.py +7 -5
- {agent_pbx-2.1.0 → agent_pbx-2.2.0}/src/agent_pbx/terminal/widget.py +218 -38
- agent_pbx-2.2.0/src/agent_pbx/terminal_editor.py +857 -0
- {agent_pbx-2.1.0 → agent_pbx-2.2.0}/src/agent_pbx/tmux.py +233 -48
- agent_pbx-2.2.0/src/agent_pbx/tmux_binary.py +188 -0
- {agent_pbx-2.1.0 → agent_pbx-2.2.0}/src/agent_pbx/tui.py +3604 -134
- {agent_pbx-2.1.0 → agent_pbx-2.2.0}/src/agent_pbx/tui_cli.py +2 -0
- agent_pbx-2.2.0/src/agent_pbx/ui/navigation.py +83 -0
- agent_pbx-2.2.0/src/agent_pbx/ui/palette_history.py +250 -0
- {agent_pbx-2.1.0 → agent_pbx-2.2.0}/src/agent_pbx/ui/panels/joplin.py +46 -0
- {agent_pbx-2.1.0 → agent_pbx-2.2.0}/src/agent_pbx/ui/theme.py +39 -16
- agent_pbx-2.2.0/src/agent_pbx/wiki_publish.py +397 -0
- {agent_pbx-2.1.0 → agent_pbx-2.2.0}/src/agent_pbx/workerbee.py +6 -0
- agent_pbx-2.2.0/src/agent_pbx/workerbee_harness.py +219 -0
- {agent_pbx-2.1.0 → agent_pbx-2.2.0}/src/agent_pbx/workerbee_mcp.py +233 -7
- agent_pbx-2.2.0/src/agent_pbx/workerbee_switcher.py +443 -0
- agent_pbx-2.1.0/README.md → agent_pbx-2.2.0/src/agent_pbx.egg-info/PKG-INFO +337 -55
- {agent_pbx-2.1.0 → agent_pbx-2.2.0}/src/agent_pbx.egg-info/SOURCES.txt +39 -0
- {agent_pbx-2.1.0 → agent_pbx-2.2.0}/src/agent_pbx.egg-info/requires.txt +4 -0
- {agent_pbx-2.1.0 → agent_pbx-2.2.0}/tests/test_codex_adapter.py +8 -0
- {agent_pbx-2.1.0 → agent_pbx-2.2.0}/tests/test_codex_config.py +31 -0
- agent_pbx-2.2.0/tests/test_codex_event_bridge.py +386 -0
- {agent_pbx-2.1.0 → agent_pbx-2.2.0}/tests/test_codex_sessions.py +39 -0
- agent_pbx-2.2.0/tests/test_codex_theme.py +72 -0
- agent_pbx-2.2.0/tests/test_dev_harness.py +164 -0
- agent_pbx-2.2.0/tests/test_docs.py +36 -0
- {agent_pbx-2.1.0 → agent_pbx-2.2.0}/tests/test_doctor.py +80 -0
- {agent_pbx-2.1.0 → agent_pbx-2.2.0}/tests/test_joplin.py +816 -6
- {agent_pbx-2.1.0 → agent_pbx-2.2.0}/tests/test_lifecycle.py +4 -1
- {agent_pbx-2.1.0 → agent_pbx-2.2.0}/tests/test_managed_runtime.py +67 -1
- {agent_pbx-2.1.0 → agent_pbx-2.2.0}/tests/test_mcp_daemon.py +171 -0
- {agent_pbx-2.1.0 → agent_pbx-2.2.0}/tests/test_mcp_tools.py +60 -0
- agent_pbx-2.2.0/tests/test_navigation.py +47 -0
- {agent_pbx-2.1.0 → agent_pbx-2.2.0}/tests/test_operator.py +109 -0
- agent_pbx-2.2.0/tests/test_palette_history.py +47 -0
- agent_pbx-2.2.0/tests/test_public_demo_fixtures.py +94 -0
- agent_pbx-2.2.0/tests/test_public_demo_policy.py +131 -0
- agent_pbx-2.2.0/tests/test_public_demo_session.py +94 -0
- agent_pbx-2.2.0/tests/test_public_demo_web.py +171 -0
- agent_pbx-2.2.0/tests/test_readme.py +34 -0
- {agent_pbx-2.1.0 → agent_pbx-2.2.0}/tests/test_release_packaging.py +17 -0
- agent_pbx-2.2.0/tests/test_release_validation.py +277 -0
- {agent_pbx-2.1.0 → agent_pbx-2.2.0}/tests/test_remote.py +1 -1
- {agent_pbx-2.1.0 → agent_pbx-2.2.0}/tests/test_runtime_tmux.py +378 -8
- {agent_pbx-2.1.0 → agent_pbx-2.2.0}/tests/test_runtime_ux.py +231 -0
- agent_pbx-2.2.0/tests/test_setup_assistant.py +187 -0
- {agent_pbx-2.1.0 → agent_pbx-2.2.0}/tests/test_store.py +120 -0
- {agent_pbx-2.1.0 → agent_pbx-2.2.0}/tests/test_terminal.py +87 -0
- agent_pbx-2.2.0/tests/test_terminal_editor.py +700 -0
- {agent_pbx-2.1.0 → agent_pbx-2.2.0}/tests/test_tmux.py +92 -13
- agent_pbx-2.2.0/tests/test_tmux_binary.py +81 -0
- {agent_pbx-2.1.0 → agent_pbx-2.2.0}/tests/test_tui.py +2812 -232
- {agent_pbx-2.1.0 → agent_pbx-2.2.0}/tests/test_ui_controllers.py +25 -0
- agent_pbx-2.2.0/tests/test_wiki_publish.py +153 -0
- agent_pbx-2.2.0/tests/test_workerbee_harness.py +169 -0
- agent_pbx-2.2.0/tests/test_workerbee_mcp.py +178 -0
- agent_pbx-2.2.0/tests/test_workerbee_switcher.py +252 -0
- {agent_pbx-2.1.0 → agent_pbx-2.2.0}/tests/test_workflow.py +48 -0
- agent_pbx-2.1.0/tests/test_workerbee_mcp.py +0 -79
- {agent_pbx-2.1.0 → agent_pbx-2.2.0}/LICENSE +0 -0
- {agent_pbx-2.1.0 → agent_pbx-2.2.0}/setup.cfg +0 -0
- {agent_pbx-2.1.0 → agent_pbx-2.2.0}/src/agent_pbx/__main__.py +0 -0
- {agent_pbx-2.1.0 → agent_pbx-2.2.0}/src/agent_pbx/agent.py +0 -0
- {agent_pbx-2.1.0 → agent_pbx-2.2.0}/src/agent_pbx/auth.py +0 -0
- {agent_pbx-2.1.0 → agent_pbx-2.2.0}/src/agent_pbx/client.py +0 -0
- {agent_pbx-2.1.0 → agent_pbx-2.2.0}/src/agent_pbx/codex/__init__.py +0 -0
- {agent_pbx-2.1.0 → agent_pbx-2.2.0}/src/agent_pbx/codex/adapter.py +0 -0
- {agent_pbx-2.1.0 → agent_pbx-2.2.0}/src/agent_pbx/codex/capabilities.py +0 -0
- {agent_pbx-2.1.0 → agent_pbx-2.2.0}/src/agent_pbx/codex/models.py +0 -0
- {agent_pbx-2.1.0 → agent_pbx-2.2.0}/src/agent_pbx/codex/profiles.py +0 -0
- {agent_pbx-2.1.0 → agent_pbx-2.2.0}/src/agent_pbx/codex/protocol.py +0 -0
- {agent_pbx-2.1.0 → agent_pbx-2.2.0}/src/agent_pbx/codex/sessions.py +0 -0
- {agent_pbx-2.1.0 → agent_pbx-2.2.0}/src/agent_pbx/codex/skills.py +0 -0
- {agent_pbx-2.1.0 → agent_pbx-2.2.0}/src/agent_pbx/codex_cli.py +0 -0
- {agent_pbx-2.1.0 → agent_pbx-2.2.0}/src/agent_pbx/compat.py +0 -0
- {agent_pbx-2.1.0 → agent_pbx-2.2.0}/src/agent_pbx/contracts.py +0 -0
- {agent_pbx-2.1.0 → agent_pbx-2.2.0}/src/agent_pbx/debug_smoke.py +0 -0
- {agent_pbx-2.1.0 → agent_pbx-2.2.0}/src/agent_pbx/envfile.py +0 -0
- {agent_pbx-2.1.0 → agent_pbx-2.2.0}/src/agent_pbx/events.py +0 -0
- {agent_pbx-2.1.0 → agent_pbx-2.2.0}/src/agent_pbx/issues.py +0 -0
- {agent_pbx-2.1.0 → agent_pbx-2.2.0}/src/agent_pbx/migration.py +0 -0
- {agent_pbx-2.1.0 → agent_pbx-2.2.0}/src/agent_pbx/pairing.py +0 -0
- {agent_pbx-2.1.0 → agent_pbx-2.2.0}/src/agent_pbx/paths.py +0 -0
- {agent_pbx-2.1.0 → agent_pbx-2.2.0}/src/agent_pbx/polling.py +0 -0
- {agent_pbx-2.1.0 → agent_pbx-2.2.0}/src/agent_pbx/project_spawn.py +0 -0
- {agent_pbx-2.1.0 → agent_pbx-2.2.0}/src/agent_pbx/pull_requests.py +0 -0
- {agent_pbx-2.1.0 → agent_pbx-2.2.0}/src/agent_pbx/remote.py +0 -0
- {agent_pbx-2.1.0 → agent_pbx-2.2.0}/src/agent_pbx/security.py +0 -0
- {agent_pbx-2.1.0 → agent_pbx-2.2.0}/src/agent_pbx/sim_agent.py +0 -0
- {agent_pbx-2.1.0 → agent_pbx-2.2.0}/src/agent_pbx/sim_client.py +0 -0
- {agent_pbx-2.1.0 → agent_pbx-2.2.0}/src/agent_pbx/skill_packs/agent-pbx-base/SKILL.md +0 -0
- {agent_pbx-2.1.0 → agent_pbx-2.2.0}/src/agent_pbx/skill_packs/agent-role/SKILL.md +0 -0
- {agent_pbx-2.1.0 → agent_pbx-2.2.0}/src/agent_pbx/skill_packs/operator-role/SKILL.md +0 -0
- {agent_pbx-2.1.0 → agent_pbx-2.2.0}/src/agent_pbx/skill_packs/review-role/SKILL.md +0 -0
- {agent_pbx-2.1.0 → agent_pbx-2.2.0}/src/agent_pbx/skill_packs/roses-architect/SKILL.md +0 -0
- {agent_pbx-2.1.0 → agent_pbx-2.2.0}/src/agent_pbx/terminal/__init__.py +0 -0
- {agent_pbx-2.1.0 → agent_pbx-2.2.0}/src/agent_pbx/terminal/keys.py +0 -0
- {agent_pbx-2.1.0 → agent_pbx-2.2.0}/src/agent_pbx/terminal/pty.py +0 -0
- {agent_pbx-2.1.0 → agent_pbx-2.2.0}/src/agent_pbx/terminal/screen.py +0 -0
- {agent_pbx-2.1.0 → agent_pbx-2.2.0}/src/agent_pbx/transcript.py +0 -0
- {agent_pbx-2.1.0 → agent_pbx-2.2.0}/src/agent_pbx/uat.py +0 -0
- {agent_pbx-2.1.0 → agent_pbx-2.2.0}/src/agent_pbx/ui/__init__.py +0 -0
- {agent_pbx-2.1.0 → agent_pbx-2.2.0}/src/agent_pbx/ui/actions.py +0 -0
- {agent_pbx-2.1.0 → agent_pbx-2.2.0}/src/agent_pbx/ui/async_jobs.py +0 -0
- {agent_pbx-2.1.0 → agent_pbx-2.2.0}/src/agent_pbx/ui/focus.py +0 -0
- {agent_pbx-2.1.0 → agent_pbx-2.2.0}/src/agent_pbx/ui/panels/__init__.py +0 -0
- {agent_pbx-2.1.0 → agent_pbx-2.2.0}/src/agent_pbx/ui/panels/editor.py +0 -0
- {agent_pbx-2.1.0 → agent_pbx-2.2.0}/src/agent_pbx/ui/panels/operators.py +0 -0
- {agent_pbx-2.1.0 → agent_pbx-2.2.0}/src/agent_pbx/ui/runtime.py +0 -0
- {agent_pbx-2.1.0 → agent_pbx-2.2.0}/src/agent_pbx.egg-info/dependency_links.txt +0 -0
- {agent_pbx-2.1.0 → agent_pbx-2.2.0}/src/agent_pbx.egg-info/entry_points.txt +0 -0
- {agent_pbx-2.1.0 → agent_pbx-2.2.0}/src/agent_pbx.egg-info/top_level.txt +0 -0
- {agent_pbx-2.1.0 → agent_pbx-2.2.0}/tests/test_agent_adoption.py +0 -0
- {agent_pbx-2.1.0 → agent_pbx-2.2.0}/tests/test_agent_instructions.py +0 -0
- {agent_pbx-2.1.0 → agent_pbx-2.2.0}/tests/test_auth_pairing.py +0 -0
- {agent_pbx-2.1.0 → agent_pbx-2.2.0}/tests/test_codex_cli.py +0 -0
- {agent_pbx-2.1.0 → agent_pbx-2.2.0}/tests/test_codex_profiles.py +0 -0
- {agent_pbx-2.1.0 → agent_pbx-2.2.0}/tests/test_compat.py +0 -0
- {agent_pbx-2.1.0 → agent_pbx-2.2.0}/tests/test_contracts.py +0 -0
- {agent_pbx-2.1.0 → agent_pbx-2.2.0}/tests/test_debug_smoke.py +0 -0
- {agent_pbx-2.1.0 → agent_pbx-2.2.0}/tests/test_demo_codex.py +0 -0
- {agent_pbx-2.1.0 → agent_pbx-2.2.0}/tests/test_events.py +0 -0
- {agent_pbx-2.1.0 → agent_pbx-2.2.0}/tests/test_health.py +0 -0
- {agent_pbx-2.1.0 → agent_pbx-2.2.0}/tests/test_issues.py +0 -0
- {agent_pbx-2.1.0 → agent_pbx-2.2.0}/tests/test_migration.py +0 -0
- {agent_pbx-2.1.0 → agent_pbx-2.2.0}/tests/test_polling.py +0 -0
- {agent_pbx-2.1.0 → agent_pbx-2.2.0}/tests/test_project_spawn.py +0 -0
- {agent_pbx-2.1.0 → agent_pbx-2.2.0}/tests/test_pull_requests.py +0 -0
- {agent_pbx-2.1.0 → agent_pbx-2.2.0}/tests/test_tui_cli.py +0 -0
- {agent_pbx-2.1.0 → agent_pbx-2.2.0}/tests/test_uat.py +0 -0
- {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.
|
|
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
|
-
|
|
67
|
-
|
|
68
|
-
|
|
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
|
-
|
|
71
|
-
PBX --> POLICY[Policy, routing, approvals, lifecycle, audit]
|
|
72
|
-
PBX --> UI[TUI, SSH, API, WSS, MCP]
|
|
83
|
+
### Interactive browser demo
|
|
73
84
|
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
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
|
-
|
|
79
|
-
|
|
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
|
|
93
|
-
[the
|
|
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
|
|
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
|
|
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.
|
|
711
|
-
|
|
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
|
|
827
|
-
|
|
828
|
-
|
|
829
|
-
|
|
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
|
|
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
|
-
|
|
913
|
-
|
|
914
|
-
|
|
915
|
-
|
|
916
|
-
|
|
917
|
-
|
|
918
|
-
|
|
919
|
-
the TUI
|
|
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
|
|
928
|
-
reference such as `@README` or `@src/ag` and press `Tab`;
|
|
929
|
-
needed project directory before completing.
|
|
930
|
-
|
|
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`, `/
|
|
1098
|
-
`/
|
|
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
|
|
1106
|
-
Codex `/
|
|
1107
|
-
known session when Agent PBX can recover
|
|
1108
|
-
|
|
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
|
|
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`,
|
|
1188
|
-
|
|
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.
|
|
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, `
|
|
1259
|
-
`F8` next alert, `F9` editor,
|
|
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. `
|
|
1308
|
-
|
|
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
|
|