talkops-opscloud 0.3.0b1__py3-none-any.whl

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 (309) hide show
  1. opscloud/__init__.py +5 -0
  2. opscloud/__main__.py +6 -0
  3. opscloud/_constants.py +53 -0
  4. opscloud/_debug.py +145 -0
  5. opscloud/_debug_buffer.py +250 -0
  6. opscloud/_textual_patches.py +367 -0
  7. opscloud/_version.py +15 -0
  8. opscloud/agent/__init__.py +27 -0
  9. opscloud/agent/config.py +168 -0
  10. opscloud/agent/factory.py +1103 -0
  11. opscloud/approval_mode.py +44 -0
  12. opscloud/backend/__init__.py +49 -0
  13. opscloud/backend/composite.py +89 -0
  14. opscloud/backend/local.py +183 -0
  15. opscloud/backend/registry.py +79 -0
  16. opscloud/backend/sandbox_config.py +107 -0
  17. opscloud/backend/sandbox_factory.py +432 -0
  18. opscloud/built_in_skills/remember/SKILL.md +124 -0
  19. opscloud/built_in_skills/skill-creator/SKILL.md +348 -0
  20. opscloud/built_in_skills/skill-creator/scripts/init_skill.py +371 -0
  21. opscloud/built_in_skills/skill-creator/scripts/quick_validate.py +165 -0
  22. opscloud/cli/__init__.py +1 -0
  23. opscloud/cli/commands/__init__.py +15 -0
  24. opscloud/cli/commands/auth.py +45 -0
  25. opscloud/cli/commands/doctor.py +100 -0
  26. opscloud/cli/commands/mcp.py +137 -0
  27. opscloud/cli/commands/threads.py +51 -0
  28. opscloud/cli/interactive.py +154 -0
  29. opscloud/cli/main.py +903 -0
  30. opscloud/cli/non_interactive.py +425 -0
  31. opscloud/cli/server_manager.py +58 -0
  32. opscloud/commands/__init__.py +19 -0
  33. opscloud/commands/_base.py +110 -0
  34. opscloud/commands/_guards.py +52 -0
  35. opscloud/commands/_router.py +146 -0
  36. opscloud/commands/_types.py +36 -0
  37. opscloud/commands/core/__init__.py +47 -0
  38. opscloud/commands/core/auth.py +94 -0
  39. opscloud/commands/core/bug.py +46 -0
  40. opscloud/commands/core/clear.py +106 -0
  41. opscloud/commands/core/cloud.py +185 -0
  42. opscloud/commands/core/compact.py +128 -0
  43. opscloud/commands/core/config_cmd.py +120 -0
  44. opscloud/commands/core/context.py +220 -0
  45. opscloud/commands/core/cost.py +44 -0
  46. opscloud/commands/core/doctor.py +535 -0
  47. opscloud/commands/core/effort.py +108 -0
  48. opscloud/commands/core/exit_cmd.py +41 -0
  49. opscloud/commands/core/fast.py +148 -0
  50. opscloud/commands/core/help_cmd.py +94 -0
  51. opscloud/commands/core/mcp.py +134 -0
  52. opscloud/commands/core/model.py +109 -0
  53. opscloud/commands/core/permissions.py +196 -0
  54. opscloud/commands/core/plugins.py +92 -0
  55. opscloud/commands/core/pool.py +108 -0
  56. opscloud/commands/core/resume.py +97 -0
  57. opscloud/commands/core/skills.py +178 -0
  58. opscloud/commands/power/__init__.py +51 -0
  59. opscloud/commands/power/agents.py +98 -0
  60. opscloud/commands/power/btw.py +85 -0
  61. opscloud/commands/power/copy.py +97 -0
  62. opscloud/commands/power/goal.py +548 -0
  63. opscloud/commands/power/loop.py +295 -0
  64. opscloud/commands/power/memory.py +287 -0
  65. opscloud/commands/power/review.py +152 -0
  66. opscloud/commands/power/rubric.py +287 -0
  67. opscloud/commands/power/runtime.py +321 -0
  68. opscloud/commands/power/skill_creator.py +70 -0
  69. opscloud/commands/power/skill_invoke.py +165 -0
  70. opscloud/commands/power/tasks.py +209 -0
  71. opscloud/commands/power/trace.py +117 -0
  72. opscloud/commands/power/ui_toggles.py +135 -0
  73. opscloud/commands/power/version.py +52 -0
  74. opscloud/commands/registry.py +176 -0
  75. opscloud/config/__init__.py +114 -0
  76. opscloud/config/adapters/__init__.py +5 -0
  77. opscloud/config/adapters/postgres.py +776 -0
  78. opscloud/config/adapters/sqlite.py +769 -0
  79. opscloud/config/aws.py +248 -0
  80. opscloud/config/cloud_profiles.py +437 -0
  81. opscloud/config/env_vars.py +81 -0
  82. opscloud/config/langsmith.py +319 -0
  83. opscloud/config/manifest.py +817 -0
  84. opscloud/config/metadata.py +205 -0
  85. opscloud/config/paths.py +604 -0
  86. opscloud/config/plugins.py +130 -0
  87. opscloud/config/settings.py +834 -0
  88. opscloud/config/store.py +453 -0
  89. opscloud/config/store_factory.py +97 -0
  90. opscloud/config/toml_config.py +562 -0
  91. opscloud/editor.py +173 -0
  92. opscloud/exceptions.py +65 -0
  93. opscloud/file_ops.py +217 -0
  94. opscloud/hooks/__init__.py +139 -0
  95. opscloud/hooks/env.py +44 -0
  96. opscloud/hooks/interrupt.py +121 -0
  97. opscloud/hooks/models/__init__.py +109 -0
  98. opscloud/hooks/models/adapters.py +19 -0
  99. opscloud/hooks/models/config.py +79 -0
  100. opscloud/hooks/models/domain.py +434 -0
  101. opscloud/hooks/models/transport.py +37 -0
  102. opscloud/hooks/tools.py +231 -0
  103. opscloud/input.py +48 -0
  104. opscloud/integrations/__init__.py +80 -0
  105. opscloud/integrations/base.py +153 -0
  106. opscloud/integrations/content_filter.py +119 -0
  107. opscloud/integrations/event_bus.py +480 -0
  108. opscloud/integrations/hooks.py +238 -0
  109. opscloud/integrations/identity.py +181 -0
  110. opscloud/integrations/notifications.py +134 -0
  111. opscloud/integrations/stream_bridge.py +397 -0
  112. opscloud/integrations/thread_store.py +81 -0
  113. opscloud/json_types.py +20 -0
  114. opscloud/mcp/__init__.py +57 -0
  115. opscloud/mcp/config.py +203 -0
  116. opscloud/mcp/discovery.py +229 -0
  117. opscloud/mcp/mcp_info.py +109 -0
  118. opscloud/mcp/middleware.py +102 -0
  119. opscloud/mcp/preload.py +505 -0
  120. opscloud/mcp/raw_config.py +149 -0
  121. opscloud/mcp/semantic_profiler.py +305 -0
  122. opscloud/mcp/session_manager.py +727 -0
  123. opscloud/mcp/trust.py +105 -0
  124. opscloud/memory/__init__.py +27 -0
  125. opscloud/memory/branch.py +61 -0
  126. opscloud/memory/guard.py +19 -0
  127. opscloud/memory/onboarding.py +120 -0
  128. opscloud/memory/registry.py +134 -0
  129. opscloud/memory/store.py +223 -0
  130. opscloud/middleware/__init__.py +106 -0
  131. opscloud/middleware/_repository_bounds.py +459 -0
  132. opscloud/middleware/ask_user.py +152 -0
  133. opscloud/middleware/auto_mode.py +60 -0
  134. opscloud/middleware/auto_mode_hitl.py +2434 -0
  135. opscloud/middleware/compaction.py +566 -0
  136. opscloud/middleware/configurable_model.py +233 -0
  137. opscloud/middleware/cost_tracking.py +1021 -0
  138. opscloud/middleware/glm_stall_recovery.py +109 -0
  139. opscloud/middleware/goal_criteria.py +1234 -0
  140. opscloud/middleware/goal_state_notice.py +712 -0
  141. opscloud/middleware/goal_tools.py +407 -0
  142. opscloud/middleware/headless_mcp_guard.py +88 -0
  143. opscloud/middleware/jev_model_router.py +1018 -0
  144. opscloud/middleware/local_context.py +460 -0
  145. opscloud/middleware/mcp_context.py +151 -0
  146. opscloud/middleware/mcp_middleware.py +146 -0
  147. opscloud/middleware/memory_guard.py +393 -0
  148. opscloud/middleware/model_retry.py +205 -0
  149. opscloud/middleware/registry.py +137 -0
  150. opscloud/middleware/reliable_rubric.py +709 -0
  151. opscloud/middleware/resume_state.py +91 -0
  152. opscloud/middleware/server_hooks.py +1189 -0
  153. opscloud/middleware/shell_allow_list.py +90 -0
  154. opscloud/middleware/skills.py +382 -0
  155. opscloud/middleware/subagent_artifacts.py +84 -0
  156. opscloud/middleware/subagent_telemetry.py +261 -0
  157. opscloud/middleware/subagents.py +243 -0
  158. opscloud/middleware/tool_filter.py +384 -0
  159. opscloud/middleware/unified_system_message.py +62 -0
  160. opscloud/model/__init__.py +37 -0
  161. opscloud/model/config.py +2992 -0
  162. opscloud/model/factory.py +477 -0
  163. opscloud/model/pool.py +459 -0
  164. opscloud/model/reasoning.py +282 -0
  165. opscloud/offload.py +173 -0
  166. opscloud/output.py +64 -0
  167. opscloud/plugins/__init__.py +189 -0
  168. opscloud/plugins/_json.py +22 -0
  169. opscloud/plugins/adapters/__init__.py +13 -0
  170. opscloud/plugins/adapters/agents.py +112 -0
  171. opscloud/plugins/adapters/commands.py +190 -0
  172. opscloud/plugins/adapters/mcp.py +363 -0
  173. opscloud/plugins/adapters/skills.py +132 -0
  174. opscloud/plugins/commands_cli.py +541 -0
  175. opscloud/plugins/discovery.py +512 -0
  176. opscloud/plugins/manifest.py +335 -0
  177. opscloud/plugins/marketplace.py +893 -0
  178. opscloud/plugins/models.py +334 -0
  179. opscloud/plugins/project_plugins.py +317 -0
  180. opscloud/plugins/protocol.py +31 -0
  181. opscloud/plugins/store.py +905 -0
  182. opscloud/plugins/substitution.py +122 -0
  183. opscloud/project_utils.py +145 -0
  184. opscloud/prompts/__init__.py +37 -0
  185. opscloud/prompts/system.py +483 -0
  186. opscloud/prompts/templates/system_prompt.md +166 -0
  187. opscloud/prompts/types.py +54 -0
  188. opscloud/rubrics/__init__.py +42 -0
  189. opscloud/rubrics/evaluator.py +404 -0
  190. opscloud/rubrics/evidence_extractor.py +229 -0
  191. opscloud/rubrics/generator.py +239 -0
  192. opscloud/rubrics/jev_compiler.py +175 -0
  193. opscloud/rubrics/jev_grader.py +297 -0
  194. opscloud/rubrics/middleware.py +8 -0
  195. opscloud/schema/__init__.py +107 -0
  196. opscloud/schema/interrupts.py +981 -0
  197. opscloud/security/__init__.py +91 -0
  198. opscloud/security/approval_mode.py +528 -0
  199. opscloud/security/approval_mode_source.py +230 -0
  200. opscloud/security/cli_ast_evaluator.py +552 -0
  201. opscloud/security/jev_classifier.py +651 -0
  202. opscloud/security/shell_safety.py +340 -0
  203. opscloud/security/unicode_security.py +439 -0
  204. opscloud/security/url_validation.py +160 -0
  205. opscloud/server/__init__.py +13 -0
  206. opscloud/server/_server_config.py +158 -0
  207. opscloud/server/server.py +242 -0
  208. opscloud/server/server_graph.py +93 -0
  209. opscloud/skills/__init__.py +91 -0
  210. opscloud/skills/commands.py +1099 -0
  211. opscloud/skills/invocation.py +200 -0
  212. opscloud/skills/load.py +388 -0
  213. opscloud/skills/loader.py +23 -0
  214. opscloud/skills/merge.py +65 -0
  215. opscloud/skills/registry.py +263 -0
  216. opscloud/skills/sources.py +174 -0
  217. opscloud/skills/trust.py +417 -0
  218. opscloud/state/__init__.py +142 -0
  219. opscloud/state/base.py +154 -0
  220. opscloud/state/cloud_context.py +262 -0
  221. opscloud/state/goal_channels.py +124 -0
  222. opscloud/state/goal_state_limits.py +175 -0
  223. opscloud/state/resume_state.py +58 -0
  224. opscloud/state/service_context.py +281 -0
  225. opscloud/state/session.py +957 -0
  226. opscloud/state/state_migration.py +86 -0
  227. opscloud/subagents/__init__.py +30 -0
  228. opscloud/subagents/loader.py +331 -0
  229. opscloud/subagents/subagents_parser.py +117 -0
  230. opscloud/subagents/types.py +25 -0
  231. opscloud/tools/__init__.py +36 -0
  232. opscloud/tools/catalog.py +37 -0
  233. opscloud/tools/display.py +24 -0
  234. opscloud/tools/fetch_url.py +176 -0
  235. opscloud/tools/goal_tools.py +423 -0
  236. opscloud/tools/registry.py +105 -0
  237. opscloud/tools/thread.py +32 -0
  238. opscloud/tools/web_search.py +215 -0
  239. opscloud/ui/__init__.py +119 -0
  240. opscloud/ui/app.py +5400 -0
  241. opscloud/ui/app.tcss +479 -0
  242. opscloud/ui/clipboard.py +147 -0
  243. opscloud/ui/command_registry.py +482 -0
  244. opscloud/ui/message_store.py +152 -0
  245. opscloud/ui/permission_store.py +360 -0
  246. opscloud/ui/preferences.py +113 -0
  247. opscloud/ui/prompt_manager.py +96 -0
  248. opscloud/ui/remote_client.py +505 -0
  249. opscloud/ui/textual_adapter.py +1269 -0
  250. opscloud/ui/theme.py +728 -0
  251. opscloud/ui/ui_help.py +415 -0
  252. opscloud/ui/widgets/__init__.py +383 -0
  253. opscloud/ui/widgets/_ask_user_types.py +81 -0
  254. opscloud/ui/widgets/_copy_spans.py +52 -0
  255. opscloud/ui/widgets/_inline_prompt.py +290 -0
  256. opscloud/ui/widgets/_js_eval_display.py +139 -0
  257. opscloud/ui/widgets/_links.py +175 -0
  258. opscloud/ui/widgets/_tool_stream.py +308 -0
  259. opscloud/ui/widgets/agent_selector.py +297 -0
  260. opscloud/ui/widgets/approval.py +741 -0
  261. opscloud/ui/widgets/ask_user.py +539 -0
  262. opscloud/ui/widgets/auth.py +695 -0
  263. opscloud/ui/widgets/auth_manager.py +214 -0
  264. opscloud/ui/widgets/auto_mode_notice.py +146 -0
  265. opscloud/ui/widgets/autocomplete.py +709 -0
  266. opscloud/ui/widgets/chat_input.py +805 -0
  267. opscloud/ui/widgets/cloud_selector.py +528 -0
  268. opscloud/ui/widgets/config_manager.py +652 -0
  269. opscloud/ui/widgets/debug_console.py +1269 -0
  270. opscloud/ui/widgets/devops_renderers.py +184 -0
  271. opscloud/ui/widgets/diff.py +237 -0
  272. opscloud/ui/widgets/effort_selector.py +166 -0
  273. opscloud/ui/widgets/goal_review.py +612 -0
  274. opscloud/ui/widgets/goal_status.py +57 -0
  275. opscloud/ui/widgets/infra_panel.py +141 -0
  276. opscloud/ui/widgets/install_confirm.py +114 -0
  277. opscloud/ui/widgets/loading.py +170 -0
  278. opscloud/ui/widgets/mcp_viewer.py +1204 -0
  279. opscloud/ui/widgets/messages.py +4461 -0
  280. opscloud/ui/widgets/model_selector.py +863 -0
  281. opscloud/ui/widgets/notification_center.py +108 -0
  282. opscloud/ui/widgets/notification_settings.py +119 -0
  283. opscloud/ui/widgets/operation_card.py +106 -0
  284. opscloud/ui/widgets/permissions_manager.py +667 -0
  285. opscloud/ui/widgets/plugin_manager.py +1212 -0
  286. opscloud/ui/widgets/pool_selector.py +376 -0
  287. opscloud/ui/widgets/preamble.py +53 -0
  288. opscloud/ui/widgets/skills_viewer.py +432 -0
  289. opscloud/ui/widgets/status.py +1037 -0
  290. opscloud/ui/widgets/subagent_panel.py +927 -0
  291. opscloud/ui/widgets/theme_selector.py +232 -0
  292. opscloud/ui/widgets/thread_selector.py +358 -0
  293. opscloud/ui/widgets/toast.py +31 -0
  294. opscloud/ui/widgets/tool_display.py +325 -0
  295. opscloud/ui/widgets/tool_renderers.py +234 -0
  296. opscloud/ui/widgets/tool_widgets.py +278 -0
  297. opscloud/ui/widgets/welcome.py +421 -0
  298. opscloud/ui/widgets/welcome_popup.py +102 -0
  299. opscloud/utils/__init__.py +24 -0
  300. opscloud/utils/cost_estimation.py +169 -0
  301. opscloud/utils/git.py +390 -0
  302. opscloud/utils/logger.py +571 -0
  303. opscloud/utils/session_stats.py +115 -0
  304. opscloud/utils/startup_error.py +37 -0
  305. talkops_opscloud-0.3.0b1.dist-info/METADATA +449 -0
  306. talkops_opscloud-0.3.0b1.dist-info/RECORD +309 -0
  307. talkops_opscloud-0.3.0b1.dist-info/WHEEL +4 -0
  308. talkops_opscloud-0.3.0b1.dist-info/entry_points.txt +2 -0
  309. talkops_opscloud-0.3.0b1.dist-info/licenses/LICENSE +175 -0
@@ -0,0 +1,86 @@
1
+ """One-time migration of legacy state files into `~/.opscloud/.state/`.
2
+
3
+ Earlier prototypes wrote internal database and auth state directly under
4
+ `~/.opscloud/`. State now lives in a dedicated `.state/` directory; this
5
+ module moves legacy files into place on startup idempotently.
6
+ """
7
+
8
+ from __future__ import annotations
9
+
10
+ import logging
11
+ from collections.abc import Iterable
12
+ from pathlib import Path
13
+
14
+ from opscloud.config.paths import DATA_DIR, STATE_DIR
15
+
16
+ logger = logging.getLogger(__name__)
17
+
18
+ _LEGACY_STATE_FILES: tuple[str, ...] = (
19
+ "sessions.db",
20
+ "sessions.db-wal",
21
+ "sessions.db-shm",
22
+ "history.jsonl",
23
+ "auth.json",
24
+ "recent_models.json",
25
+ "mcp_trust.json",
26
+ )
27
+
28
+
29
+ def _iter_migrations(
30
+ config_dir: Path,
31
+ state_dir: Path,
32
+ names: Iterable[str],
33
+ ) -> Iterable[tuple[Path, Path]]:
34
+ for name in names:
35
+ yield config_dir / name, state_dir / name
36
+
37
+
38
+ def migrate_legacy_state(
39
+ *,
40
+ config_dir: Path = DATA_DIR,
41
+ state_dir: Path = STATE_DIR,
42
+ ) -> None:
43
+ """Move legacy state entries from `config_dir` into `state_dir`.
44
+
45
+ Idempotent: skips entries whose destination already exists or whose source
46
+ does not exist. Errors on individual entries are logged and swallowed so
47
+ an unmovable file never prevents startup.
48
+ """
49
+ try:
50
+ if not config_dir.is_dir():
51
+ return
52
+ except OSError:
53
+ logger.debug("Could not stat %s; skipping state migration", config_dir, exc_info=True)
54
+ return
55
+
56
+ pending: list[tuple[Path, Path]] = []
57
+ for src, dst in _iter_migrations(config_dir, state_dir, _LEGACY_STATE_FILES):
58
+ try:
59
+ if not src.exists():
60
+ continue
61
+ if dst.exists():
62
+ continue
63
+ pending.append((src, dst))
64
+ except OSError:
65
+ continue
66
+
67
+ if not pending:
68
+ return
69
+
70
+ try:
71
+ state_dir.mkdir(parents=True, exist_ok=True)
72
+ except OSError:
73
+ logger.warning("Could not create state directory %s; skipping migration", state_dir)
74
+ return
75
+
76
+ for src, dst in pending:
77
+ try:
78
+ src.rename(dst)
79
+ logger.info("Migrated legacy state %s -> %s", src, dst)
80
+ except OSError as exc:
81
+ logger.warning("Failed to migrate %s -> %s: %s", src, dst, exc)
82
+
83
+
84
+ __all__ = [
85
+ "migrate_legacy_state",
86
+ ]
@@ -0,0 +1,30 @@
1
+ """Subagents module for OpsCloud.
2
+
3
+ Provides subagent metadata types, filesystem discovery, and dynamic agent plugin loading.
4
+ """
5
+
6
+ from opscloud.subagents.loader import (
7
+ get_built_in_subagents,
8
+ list_subagents,
9
+ list_subagents_async,
10
+ load_async_subagents,
11
+ load_async_subagents_async,
12
+ parse_subagent_file,
13
+ )
14
+ from opscloud.subagents.subagents_parser import (
15
+ parse_built_in_subagents,
16
+ parse_subagent_bundle,
17
+ )
18
+ from opscloud.subagents.types import SubagentMetadata
19
+
20
+ __all__ = [
21
+ "SubagentMetadata",
22
+ "get_built_in_subagents",
23
+ "list_subagents",
24
+ "list_subagents_async",
25
+ "load_async_subagents",
26
+ "load_async_subagents_async",
27
+ "parse_built_in_subagents",
28
+ "parse_subagent_bundle",
29
+ "parse_subagent_file",
30
+ ]
@@ -0,0 +1,331 @@
1
+ """Loader for custom and dynamic subagent definitions in OpsCloud.
2
+
3
+ OpsCloud is a terminal-based coding and cloud operations agent (CLI & TUI).
4
+ Unlike containerized web backends, subagents in OpsCloud are strictly dynamic:
5
+ - **No built-in subagents**: Built-in subagents are not bundled; domain operators
6
+ are supplied dynamically through **Agent Plugins**, project directories, and user configurations.
7
+ - **Dynamic Plugin Subagents**: Agent plugins (plugins with an ``agents/`` directory or
8
+ explicit agent manifests) bundle subagent markdown definitions, scoped skills, and isolated MCP servers.
9
+ - **Project and User Definitions**: Custom subagents defined in ``.opscloud/agents/`` or ``~/.opscloud/agents/``.
10
+ - **Filesystem & Config as Source of Truth**: No database synchronizations or container rehydration.
11
+ - **Async Remote Subagents**: Defined in ``config.toml`` under ``[async_subagents]``.
12
+ """
13
+
14
+ from __future__ import annotations
15
+
16
+ import os
17
+ from pathlib import Path
18
+ import re
19
+ from typing import Any
20
+
21
+ from deepagents.middleware.async_subagents import AsyncSubAgent
22
+ import yaml
23
+
24
+ from opscloud.config import paths
25
+ from opscloud.subagents.types import SubagentMetadata
26
+ from opscloud.utils.logger import get_logger
27
+
28
+ logger = get_logger(__name__)
29
+
30
+
31
+ def _parse_subagent_file(file_path: Path, *, fallback_name: str | None = None) -> SubagentMetadata | None:
32
+ """Parse a subagent markdown file with YAML frontmatter.
33
+
34
+ The file must have YAML frontmatter (delimited by ---) containing at minimum
35
+ a 'description' field. The body of the file becomes the system_prompt.
36
+ """
37
+ try:
38
+ content = file_path.read_text(encoding="utf-8")
39
+ except OSError as exc:
40
+ logger.warning("Skipping subagent %s: could not read file (%s)", file_path, exc)
41
+ return None
42
+
43
+ match = re.match(r"^---\s*\n(.*?)\n---\s*\n?(.*)$", content, re.DOTALL)
44
+ if not match:
45
+ logger.debug("Skipping subagent %s: missing YAML frontmatter block", file_path)
46
+ return None
47
+
48
+ try:
49
+ frontmatter = yaml.safe_load(match.group(1))
50
+ except yaml.YAMLError as exc:
51
+ logger.warning("Skipping subagent %s: invalid YAML frontmatter (%s)", file_path, exc)
52
+ return None
53
+
54
+ if not isinstance(frontmatter, dict):
55
+ return None
56
+
57
+ name_value = frontmatter.get("name", fallback_name)
58
+ description_value = frontmatter.get("description")
59
+ model = frontmatter.get("model")
60
+ raw_skills = frontmatter.get("skills")
61
+ raw_tools = frontmatter.get("tools")
62
+ raw_permission_tier = frontmatter.get("permission_tier")
63
+
64
+ name = name_value.strip() if isinstance(name_value, str) and name_value.strip() else None
65
+ description = (
66
+ description_value.strip() if isinstance(description_value, str) and description_value.strip() else None
67
+ )
68
+
69
+ if name is None or description is None:
70
+ return None
71
+
72
+ if isinstance(raw_skills, str):
73
+ skills: list[str] | None = [s.strip() for s in raw_skills.split(",") if s.strip()]
74
+ elif isinstance(raw_skills, list):
75
+ skills = [str(s) for s in raw_skills]
76
+ else:
77
+ skills = None
78
+
79
+ if isinstance(raw_tools, str):
80
+ tools: list[str] | None = [t.strip() for t in raw_tools.split(",") if t.strip()]
81
+ elif isinstance(raw_tools, list):
82
+ tools = [str(t) for t in raw_tools]
83
+ else:
84
+ tools = None
85
+
86
+ raw_mcp_config = frontmatter.get("mcp_config")
87
+ raw_mcp_files = frontmatter.get("mcp_files")
88
+ raw_capabilities = frontmatter.get("capabilities")
89
+
90
+ mcp_config = dict(raw_mcp_config) if isinstance(raw_mcp_config, dict) else None
91
+ mcp_files = [str(f) for f in raw_mcp_files] if isinstance(raw_mcp_files, list) else None
92
+ capabilities = list(raw_capabilities) if isinstance(raw_capabilities, list) else None
93
+
94
+ meta: SubagentMetadata = {
95
+ "name": name,
96
+ "description": description,
97
+ "system_prompt": match.group(2).strip(),
98
+ "model": model,
99
+ "skills": skills,
100
+ "tools": tools,
101
+ "permission_tier": raw_permission_tier if isinstance(raw_permission_tier, str) else None,
102
+ "source": "custom",
103
+ "path": str(file_path),
104
+ }
105
+ if capabilities is not None:
106
+ meta["capabilities"] = capabilities
107
+ if mcp_config is not None:
108
+ meta["mcp_config"] = mcp_config
109
+ if mcp_files is not None:
110
+ meta["mcp_files"] = mcp_files
111
+
112
+ return meta
113
+
114
+
115
+ parse_subagent_file = _parse_subagent_file
116
+
117
+
118
+ def _scan_subagents_dir(agents_dir: Path, source: str) -> dict[str, SubagentMetadata]:
119
+ """Scan a directory for subagent definitions.
120
+
121
+ Expected formats:
122
+ - ``agents_dir/{name}/AGENTS.md``
123
+ - ``agents_dir/{name}.md``
124
+ - Any markdown file directly under ``agents_dir/``
125
+ """
126
+ subagents: dict[str, SubagentMetadata] = {}
127
+ if not agents_dir.exists() or not agents_dir.is_dir():
128
+ return subagents
129
+
130
+ for entry in agents_dir.iterdir():
131
+ if entry.is_dir():
132
+ md_file = entry / "AGENTS.md"
133
+ if not md_file.exists():
134
+ direct_md = entry / f"{entry.name}.md"
135
+ if direct_md.exists():
136
+ md_file = direct_md
137
+ else:
138
+ candidates = list(entry.glob("*.md"))
139
+ if candidates:
140
+ md_file = candidates[0]
141
+
142
+ if md_file.exists():
143
+ parsed = _parse_subagent_file(md_file, fallback_name=entry.name)
144
+ if parsed:
145
+ parsed["source"] = source
146
+ bundle_mcp = entry / ".mcp.json"
147
+ if bundle_mcp.exists() and "mcp_files" not in parsed:
148
+ parsed["mcp_files"] = [str(bundle_mcp)]
149
+ subagents[parsed["name"]] = parsed
150
+ elif entry.is_file() and entry.suffix.lower() == ".md":
151
+ parsed = _parse_subagent_file(entry, fallback_name=entry.stem)
152
+ if parsed:
153
+ parsed["source"] = source
154
+ subagents[parsed["name"]] = parsed
155
+
156
+ return subagents
157
+
158
+
159
+ _load_subagents_from_dir = _scan_subagents_dir
160
+
161
+
162
+ def get_built_in_subagents() -> list[SubagentMetadata]:
163
+ """Return built-in subagents.
164
+
165
+ In OpsCloud, there are no static built-in subagents; all dynamic agents
166
+ are provided via Agent Plugins, project definitions, or user configuration.
167
+ This function returns an empty list for backward compatibility.
168
+ """
169
+ return []
170
+
171
+
172
+ def list_subagents(
173
+ *,
174
+ user_agents_dir: Path | None = None,
175
+ project_agents_dir: Path | None = None,
176
+ project_root: Path | None = None,
177
+ include_plugins: bool = True,
178
+ include_builtin: bool = False, # noqa: ARG001 - kept for backward compatibility
179
+ store: Any = None, # noqa: ARG001 - kept for backward compatibility
180
+ ) -> list[SubagentMetadata]:
181
+ """List subagents from user directories, project directories, and agent plugins.
182
+
183
+ Precedence order:
184
+ 1. User subagents (lowest precedence)
185
+ 2. Project subagents (override user subagents of the same name)
186
+ 3. Plugin subagents (namespaced by plugin_id, e.g. ``my-plugin@marketplace:subagent``)
187
+
188
+ Args:
189
+ user_agents_dir: User-level agents directory (defaults to ``~/.opscloud/agents``).
190
+ project_agents_dir: Project-level agents directory (defaults to ``{project_root}/.opscloud/agents``).
191
+ project_root: Active project worktree root directory.
192
+ include_plugins: Whether to discover agent plugins from the project/marketplace.
193
+ include_builtin: Kept for compatibility (always empty in OpsCloud).
194
+ store: Kept for compatibility.
195
+
196
+ Returns:
197
+ List of resolved SubagentMetadata instances.
198
+ """
199
+ discovered: dict[str, SubagentMetadata] = {}
200
+
201
+ # 1. User subagents (defaults to ~/.opscloud/agents/ and ~/.agents/)
202
+ resolved_user_dir = user_agents_dir or paths.user_agents_dir()
203
+ if resolved_user_dir.is_dir():
204
+ discovered.update(_scan_subagents_dir(resolved_user_dir, source="user"))
205
+
206
+ # Also check ~/.agents/ if different
207
+ shared_agents_dir = paths.AGENTS_SHARED_DIR / "agents"
208
+ if shared_agents_dir.is_dir() and shared_agents_dir != resolved_user_dir:
209
+ discovered.update(_scan_subagents_dir(shared_agents_dir, source="user-shared"))
210
+
211
+ # 2. Project subagents (take precedence over user subagents)
212
+ resolved_proj_dir = project_agents_dir
213
+ if resolved_proj_dir is None and project_root is not None:
214
+ candidate = paths.project_agents_dir(project_root)
215
+ if candidate.is_dir():
216
+ resolved_proj_dir = candidate
217
+ elif (project_root / ".agents").is_dir():
218
+ resolved_proj_dir = project_root / ".agents"
219
+ elif (project_root / "agents").is_dir():
220
+ resolved_proj_dir = project_root / "agents"
221
+
222
+ if resolved_proj_dir is not None and resolved_proj_dir.is_dir():
223
+ discovered.update(_scan_subagents_dir(resolved_proj_dir, source="project"))
224
+
225
+ # 3. Dynamic Agent Plugins (marketplace & project-local plugins)
226
+ if include_plugins:
227
+ try:
228
+ from opscloud.plugins.adapters.agents import discover_plugin_subagents
229
+
230
+ plugin_metas = discover_plugin_subagents(project_root=project_root)
231
+ for p_meta in plugin_metas:
232
+ sub_name = p_meta.get("name")
233
+ if sub_name:
234
+ discovered[sub_name] = p_meta
235
+ except Exception as exc:
236
+ logger.debug("Plugin subagents discovery encountered non-fatal error: %s", exc)
237
+
238
+ return list(discovered.values())
239
+
240
+
241
+ async def list_subagents_async(
242
+ *,
243
+ user_agents_dir: Path | None = None,
244
+ project_agents_dir: Path | None = None,
245
+ project_root: Path | None = None,
246
+ include_plugins: bool = True,
247
+ include_builtin: bool = False,
248
+ store: Any = None,
249
+ ) -> list[SubagentMetadata]:
250
+ """Async wrapper around list_subagents for backward compatibility."""
251
+ return list_subagents(
252
+ user_agents_dir=user_agents_dir,
253
+ project_agents_dir=project_agents_dir,
254
+ project_root=project_root,
255
+ include_plugins=include_plugins,
256
+ include_builtin=include_builtin,
257
+ store=store,
258
+ )
259
+
260
+
261
+ def load_async_subagents(
262
+ config_path: Path | None = None,
263
+ *,
264
+ store: Any = None, # noqa: ARG001 - kept for backward compatibility
265
+ ) -> list[AsyncSubAgent]:
266
+ """Load async subagent definitions from config.toml.
267
+
268
+ Reads the ``[async_subagents]`` section where each sub-table defines a remote
269
+ LangGraph deployment to expose as an async subagent tool:
270
+
271
+ ```toml
272
+ [async_subagents.researcher]
273
+ description = "Research complex topics on the web"
274
+ graph_id = "researcher"
275
+ url = "http://localhost:8123"
276
+ ```
277
+ """
278
+ agents: list[AsyncSubAgent] = []
279
+ resolved_config_path = config_path or paths.CONFIG_PATH
280
+
281
+ if not resolved_config_path or not resolved_config_path.exists():
282
+ return agents
283
+
284
+ try:
285
+ import tomllib
286
+
287
+ with resolved_config_path.open("rb") as f:
288
+ data = tomllib.load(f)
289
+
290
+ section = data.get("async_subagents")
291
+ if isinstance(section, dict):
292
+ required = {"description", "graph_id"}
293
+ for name, spec in section.items():
294
+ if not isinstance(spec, dict):
295
+ continue
296
+ if not required.issubset(spec.keys()):
297
+ continue
298
+ agent_entry: AsyncSubAgent = {
299
+ "name": name,
300
+ "description": str(spec["description"]),
301
+ "graph_id": str(spec["graph_id"]),
302
+ }
303
+ if "url" in spec and isinstance(spec["url"], str):
304
+ agent_entry["url"] = os.path.expandvars(spec["url"])
305
+ if "headers" in spec and isinstance(spec["headers"], dict):
306
+ agent_entry["headers"] = {k: os.path.expandvars(str(v)) for k, v in spec["headers"].items()}
307
+ agents.append(agent_entry)
308
+ except Exception as exc:
309
+ logger.debug("Could not read async subagents from %s: %s", resolved_config_path, exc)
310
+
311
+ return agents
312
+
313
+
314
+ async def load_async_subagents_async(
315
+ config_path: Path | None = None,
316
+ *,
317
+ store: Any = None,
318
+ ) -> list[AsyncSubAgent]:
319
+ """Async wrapper around load_async_subagents."""
320
+ return load_async_subagents(config_path=config_path, store=store)
321
+
322
+
323
+ __all__ = [
324
+ "SubagentMetadata",
325
+ "get_built_in_subagents",
326
+ "list_subagents",
327
+ "list_subagents_async",
328
+ "load_async_subagents",
329
+ "load_async_subagents_async",
330
+ "parse_subagent_file",
331
+ ]
@@ -0,0 +1,117 @@
1
+ """Parser for built-in subagent bundle directories and plugin-style subagent assets."""
2
+
3
+ from __future__ import annotations
4
+
5
+ from pathlib import Path
6
+ import re
7
+
8
+ from opscloud.subagents.types import SubagentMetadata
9
+ from opscloud.utils.logger import get_logger
10
+
11
+ logger = get_logger(__name__)
12
+
13
+
14
+ def _discover_local_skill_names(skills_dir: Path) -> list[str]:
15
+ """Discover all skill names from SKILL.md frontmatter and directory names under skills_dir."""
16
+ if not skills_dir.exists() or not skills_dir.is_dir():
17
+ return []
18
+
19
+ names: set[str] = set()
20
+ for entry in skills_dir.rglob("SKILL.md"):
21
+ if entry.is_file():
22
+ names.add(entry.parent.name)
23
+ try:
24
+ content = entry.read_text(encoding="utf-8")
25
+ match = re.match(r"^---\s*\n(.*?)\n---\s*\n?", content, re.DOTALL)
26
+ if match:
27
+ import yaml
28
+
29
+ frontmatter = yaml.safe_load(match.group(1))
30
+ if isinstance(frontmatter, dict) and frontmatter.get("name"):
31
+ declared_name = str(frontmatter["name"]).strip()
32
+ if declared_name:
33
+ names.add(declared_name)
34
+ except Exception as exc:
35
+ logger.debug("Could not parse SKILL.md at %s: %s", entry, exc)
36
+
37
+ return sorted(names)
38
+
39
+
40
+ def parse_subagent_bundle(bundle_dir: Path, source: str = "built-in") -> list[SubagentMetadata]:
41
+ """Parse a single subagent bundle directory (containing agents/, skills/, and optional .mcp.json)."""
42
+ from opscloud.subagents.loader import _parse_subagent_file
43
+
44
+ subagents: list[SubagentMetadata] = []
45
+ if not bundle_dir.exists() or not bundle_dir.is_dir():
46
+ return subagents
47
+
48
+ agents_dir = bundle_dir / "agents"
49
+ agent_files: list[Path] = []
50
+
51
+ if agents_dir.exists() and agents_dir.is_dir():
52
+ for entry in agents_dir.iterdir():
53
+ if entry.is_file() and entry.suffix.lower() == ".md":
54
+ agent_files.append(entry)
55
+ elif entry.is_dir():
56
+ sub_agents_file = entry / "AGENTS.md"
57
+ if sub_agents_file.is_file():
58
+ agent_files.append(sub_agents_file)
59
+ else:
60
+ direct_file = bundle_dir / "AGENTS.md"
61
+ if direct_file.is_file():
62
+ agent_files.append(direct_file)
63
+
64
+ skills_dir = bundle_dir / "skills"
65
+ local_skill_names = _discover_local_skill_names(skills_dir)
66
+ mcp_file = bundle_dir / ".mcp.json"
67
+ has_mcp = mcp_file.exists() and mcp_file.is_file()
68
+
69
+ for file_path in agent_files:
70
+ meta = _parse_subagent_file(file_path, fallback_name=bundle_dir.name)
71
+ if not meta:
72
+ continue
73
+
74
+ meta["source"] = source
75
+ meta["path"] = str(file_path)
76
+
77
+ if not meta.get("skills") and local_skill_names:
78
+ meta["skills"] = list(local_skill_names)
79
+
80
+ if has_mcp and "mcp_files" not in meta and "mcp_config" not in meta:
81
+ meta["mcp_files"] = [str(mcp_file)]
82
+
83
+ subagents.append(meta)
84
+
85
+ return subagents
86
+
87
+
88
+ def parse_built_in_subagents(
89
+ built_in_root: Path | None = None,
90
+ ) -> list[SubagentMetadata]:
91
+ """Discover and parse all built-in subagent bundles from ``opscloud/built_in_subagents/``."""
92
+ if built_in_root is None:
93
+ built_in_root = Path(__file__).parent.parent / "built_in_subagents"
94
+
95
+ subagents: list[SubagentMetadata] = []
96
+ if not built_in_root.exists() or not built_in_root.is_dir():
97
+ return subagents
98
+
99
+ for bundle_dir in sorted(built_in_root.iterdir()):
100
+ if bundle_dir.is_dir() and not bundle_dir.name.startswith((".", "_")):
101
+ subagents.extend(parse_subagent_bundle(bundle_dir, source="built-in"))
102
+
103
+ return subagents
104
+
105
+
106
+ def parse_subagent_file(file_path: Path, *, fallback_name: str | None = None) -> SubagentMetadata | None:
107
+ """Parse a subagent markdown file with YAML frontmatter."""
108
+ from opscloud.subagents.loader import _parse_subagent_file
109
+
110
+ return _parse_subagent_file(file_path, fallback_name=fallback_name)
111
+
112
+
113
+ __all__ = [
114
+ "parse_built_in_subagents",
115
+ "parse_subagent_bundle",
116
+ "parse_subagent_file",
117
+ ]
@@ -0,0 +1,25 @@
1
+ """Type definitions for subagent metadata."""
2
+
3
+ from typing import Any, NotRequired, TypedDict
4
+
5
+
6
+ class SubagentMetadata(TypedDict):
7
+ """Metadata for a custom subagent loaded from filesystem."""
8
+
9
+ name: str
10
+ description: str
11
+ system_prompt: str
12
+ model: NotRequired[str | None]
13
+ skills: NotRequired[list[str] | None]
14
+ tools: NotRequired[list[str] | None]
15
+ capabilities: NotRequired[list[dict[str, Any]] | None]
16
+ mcp_config: NotRequired[dict[str, Any] | None]
17
+ mcp_files: NotRequired[list[str] | None]
18
+ middleware: NotRequired[list[Any] | None]
19
+ permission_tier: NotRequired[str | None]
20
+ is_plugin: NotRequired[bool]
21
+ plugin_id: NotRequired[str | None]
22
+ bundle_dir: NotRequired[str | None]
23
+ skills_dir: NotRequired[str | None]
24
+ source: str
25
+ path: str
@@ -0,0 +1,36 @@
1
+ """Tools catalog and registry for OpsCloud."""
2
+
3
+ from __future__ import annotations
4
+
5
+ from opscloud.tools.catalog import register_all_tools
6
+ from opscloud.tools.display import (
7
+ format_json_output,
8
+ format_tool_error,
9
+ format_tool_success,
10
+ )
11
+ from opscloud.tools.fetch_url import fetch_url
12
+ from opscloud.tools.goal_tools import get_goal, get_rubric, update_goal
13
+ from opscloud.tools.registry import ToolRegistry
14
+ from opscloud.tools.thread import get_current_thread_id
15
+ from opscloud.tools.web_search import (
16
+ create_web_search_tool,
17
+ is_web_search_tool,
18
+ web_search,
19
+ )
20
+
21
+ __all__ = [
22
+ "ToolRegistry",
23
+ "create_web_search_tool",
24
+ "fetch_url",
25
+ "format_json_output",
26
+ "format_tool_error",
27
+ "format_tool_success",
28
+ "get_current_thread_id",
29
+ "get_goal",
30
+ "get_rubric",
31
+ "is_web_search_tool",
32
+ "register_all_tools",
33
+ "update_goal",
34
+ "web_search",
35
+ ]
36
+
@@ -0,0 +1,37 @@
1
+ """Catalog of built-in tools for OpsCloud."""
2
+
3
+ from __future__ import annotations
4
+
5
+ from typing import Any
6
+
7
+ from opscloud.tools.fetch_url import fetch_url
8
+ from opscloud.tools.goal_tools import (
9
+ get_goal,
10
+ get_rubric,
11
+ update_goal,
12
+ )
13
+ from opscloud.tools.registry import ToolRegistry
14
+ from opscloud.tools.thread import get_current_thread_id
15
+ from opscloud.tools.web_search import create_web_search_tool, web_search
16
+
17
+
18
+ def register_all_tools() -> None:
19
+ """Register all available tools with the ToolRegistry."""
20
+ registry = ToolRegistry.get_instance()
21
+
22
+ # Core general-purpose tools
23
+ def _build_web_search(**kwargs: Any):
24
+ api_key = kwargs.get("api_key")
25
+ if api_key and isinstance(api_key, str):
26
+ return create_web_search_tool(api_key)
27
+ return web_search
28
+
29
+ registry.register("web_search", _build_web_search, category="web")
30
+ registry.register("fetch_url", lambda **kwargs: fetch_url, category="web")
31
+ registry.register("get_current_thread_id", lambda **kwargs: get_current_thread_id, category="system")
32
+
33
+ # Goal and Rubric tools
34
+ registry.register("get_rubric", lambda **kwargs: get_rubric, category="goal")
35
+ registry.register("get_goal", lambda **kwargs: get_goal, category="goal")
36
+ registry.register("update_goal", lambda **kwargs: update_goal, category="goal")
37
+
@@ -0,0 +1,24 @@
1
+ """Display helpers for rendering tool outputs with syntax highlighting."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import json
6
+ from typing import Any
7
+
8
+
9
+ def format_tool_error(error_msg: str) -> str:
10
+ """Format an error message with ANSI red color."""
11
+ return f"\033[91mError: {error_msg}\033[0m"
12
+
13
+
14
+ def format_tool_success(msg: str) -> str:
15
+ """Format a success message with ANSI green color."""
16
+ return f"\033[92mSuccess: {msg}\033[0m"
17
+
18
+
19
+ def format_json_output(data: Any) -> str:
20
+ """Format dictionary/JSON output as a pretty printed string."""
21
+ try:
22
+ return json.dumps(data, indent=2)
23
+ except Exception:
24
+ return str(data)