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,604 @@
1
+ """Centralized filesystem-path definitions for opscloud.
2
+
3
+ This module is the **single source of truth** for every directory and file
4
+ opscloud reads or writes at runtime. It is intentionally dependency-free (no
5
+ sibling-module imports, no third-party packages) so any module can import
6
+ from it without triggering circular or expensive imports.
7
+ """
8
+
9
+ from __future__ import annotations
10
+
11
+ import errno
12
+ from opscloud.utils.logger import get_logger
13
+ from enum import StrEnum
14
+ from pathlib import Path
15
+ from typing import Final
16
+
17
+ logger = get_logger(__name__)
18
+
19
+ # ── Constants ────────────────────────────────────────────
20
+
21
+ ENV_PREFIX: Final[str] = "OPSCLOUD_"
22
+ """All opscloud-specific env vars use this prefix."""
23
+
24
+ DEFAULT_AGENT_NAME: Final[str] = "opscloud"
25
+ """Default agent / assistant identifier when no -a flag is given."""
26
+
27
+ # ── Root directories ─────────────────────────────────────
28
+
29
+ DATA_DIR: Final[Path] = Path.home() / ".opscloud"
30
+ """``~/.opscloud/`` — Top-level user data directory."""
31
+
32
+ OPSCLOUD_HOME: Final[Path] = DATA_DIR
33
+ USER_HOME: Final[Path] = Path.home()
34
+
35
+ STATE_DIR: Final[Path] = DATA_DIR / ".state"
36
+ """``~/.opscloud/.state/`` — Machine-managed state (never hand-edit)."""
37
+
38
+ AGENTS_SHARED_DIR: Final[Path] = Path.home() / ".agents"
39
+ """``~/.agents/`` — Tool-agnostic data (shared across AI CLIs)."""
40
+
41
+ # ── User-facing config files (human-editable) ────────────
42
+
43
+ CONFIG_PATH: Final[Path] = DATA_DIR / "config.toml"
44
+ CONFIG_FILE_PATH: Final[Path] = CONFIG_PATH
45
+ """``~/.opscloud/config.toml`` — Main configuration file."""
46
+
47
+ GLOBAL_ENV_PATH: Final[Path] = DATA_DIR / ".env"
48
+ """``~/.opscloud/.env`` — Global env vars / API keys."""
49
+
50
+ HOOKS_PATH: Final[Path] = DATA_DIR / "hooks.json"
51
+ """``~/.opscloud/hooks.json`` — Lifecycle hooks."""
52
+
53
+ GLOBAL_MCP_PATH: Final[Path] = DATA_DIR / ".mcp.json"
54
+ """``~/.opscloud/.mcp.json`` — Global MCP server definitions."""
55
+
56
+ CONVERSATION_HISTORY_DIR: Final[Path] = DATA_DIR / "conversation_history"
57
+ """``~/.opscloud/conversation_history/`` — Offload conversation logs."""
58
+
59
+ LOGS_DIR: Final[Path] = DATA_DIR / "logs"
60
+
61
+ # ── Managed state files (.state/) ────────────────────────
62
+
63
+ AUTH_PATH: Final[Path] = STATE_DIR / "auth.json"
64
+ """``~/.opscloud/.state/auth.json`` — Credential store."""
65
+
66
+ SESSIONS_DB_PATH: Final[Path] = STATE_DIR / "sessions.db"
67
+ """``~/.opscloud/.state/sessions.db`` — SQLite conversation checkpoints."""
68
+
69
+ SERVER_DIR: Final[Path] = STATE_DIR / "server"
70
+ SERVER_RUNTIME_DIR: Final[Path] = SERVER_DIR
71
+
72
+ HISTORY_PATH: Final[Path] = STATE_DIR / "history.jsonl"
73
+ """``~/.opscloud/.state/history.jsonl`` — Command input history."""
74
+
75
+ RECENT_MODELS_PATH: Final[Path] = STATE_DIR / "recent_models.json"
76
+ """``~/.opscloud/.state/recent_models.json`` — Last /model switch."""
77
+
78
+ MCP_TRUST_PATH: Final[Path] = STATE_DIR / "mcp_trust.json"
79
+ """``~/.opscloud/.state/mcp_trust.json`` — Saved MCP project approvals."""
80
+
81
+ SKILL_TRUST_PATH: Final[Path] = STATE_DIR / "skill_trust.json"
82
+ """``~/.opscloud/.state/skill_trust.json`` — Skill trust decisions."""
83
+
84
+ ONBOARDING_MARKER: Final[Path] = STATE_DIR / "onboarding_complete"
85
+ """``~/.opscloud/.state/onboarding_complete`` — First-run marker."""
86
+
87
+ # ── Plugin directory and state files ─────────────────────────
88
+
89
+ PLUGINS_DIR: Final[Path] = DATA_DIR / "plugins"
90
+ PLUGINS_CACHE_DIR: Final[Path] = PLUGINS_DIR / "cache"
91
+ PLUGIN_CACHE_DIR: Final[Path] = PLUGINS_CACHE_DIR
92
+ PLUGIN_DATA_DIR: Final[Path] = PLUGINS_DIR / "data"
93
+ PLUGIN_MARKETPLACES_DIR: Final[Path] = PLUGINS_DIR / "marketplaces"
94
+
95
+ PLUGIN_INSTALLED_PATH: Final[Path] = STATE_DIR / "installed_plugins.json"
96
+ PLUGIN_STATE_PATH: Final[Path] = STATE_DIR / "plugin_state.json"
97
+ PLUGIN_MARKETPLACES_PATH: Final[Path] = STATE_DIR / "plugin_marketplaces.json"
98
+
99
+ USER_SETTINGS_PATH: Final[Path] = DATA_DIR / "settings.json"
100
+
101
+
102
+ def project_opscloud_dir(project_root: Path) -> Path:
103
+ """Return ``{project_root}/.opscloud`` — project-specific opscloud metadata dir."""
104
+ return project_root / ".opscloud"
105
+
106
+
107
+ def project_settings_path(project_root: Path) -> Path:
108
+ """Return ``{project_root}/.opscloud/settings.json`` — project-scope settings."""
109
+ opscloud_settings = project_opscloud_dir(project_root) / "settings.json"
110
+ if not opscloud_settings.exists() and (project_root / ".opscode" / "settings.json").exists():
111
+ return project_root / ".opscode" / "settings.json"
112
+ return opscloud_settings
113
+
114
+
115
+ def project_local_settings_path(project_root: Path) -> Path:
116
+ """Return ``{project_root}/.opscloud/settings.local.json`` — local-scope settings."""
117
+ opscloud_local = project_opscloud_dir(project_root) / "settings.local.json"
118
+ if not opscloud_local.exists() and (project_root / ".opscode" / "settings.local.json").exists():
119
+ return project_root / ".opscode" / "settings.local.json"
120
+ return opscloud_local
121
+
122
+ # ── Project root markers ─────────────────────────────────
123
+
124
+ PROJECT_ROOT_MARKERS: Final[tuple[str, ...]] = (
125
+ ".opscloud",
126
+ ".git",
127
+ "terragrunt.hcl",
128
+ "main.tf",
129
+ "cdk.json",
130
+ "template.yaml",
131
+ "template.yml",
132
+ "samconfig.toml",
133
+ "Pulumi.yaml",
134
+ "Chart.yaml",
135
+ "ansible.cfg",
136
+ "pyproject.toml",
137
+ "package.json",
138
+ "Makefile",
139
+ )
140
+
141
+ DOTENV_DENIED_ENV_KEYS: Final[frozenset[str]] = frozenset(
142
+ {
143
+ "PATH",
144
+ "HOME",
145
+ "USER",
146
+ "LOGNAME",
147
+ "SHELL",
148
+ "TERM",
149
+ "DISPLAY",
150
+ "LD_PRELOAD",
151
+ "LD_LIBRARY_PATH",
152
+ "DYLD_LIBRARY_PATH",
153
+ "DYLD_INSERT_LIBRARIES",
154
+ "PYTHONPATH",
155
+ "PYTHONSTARTUP",
156
+ "PYTHONHOME",
157
+ "NODE_PATH",
158
+ "NODE_OPTIONS",
159
+ "HISTFILE",
160
+ "HISTSIZE",
161
+ "SSH_AUTH_SOCK",
162
+ "GPG_AGENT_INFO",
163
+ "TMPDIR",
164
+ "TEMP",
165
+ "TMP",
166
+ }
167
+ )
168
+
169
+ RELOADABLE_FIELDS: Final[frozenset[str]] = frozenset(
170
+ {
171
+ "model_name",
172
+ "model_provider",
173
+ "reasoning_effort",
174
+ "cloud_provider",
175
+ "aws_region",
176
+ "aws_profile",
177
+ "shell_allow_list",
178
+ "theme",
179
+ }
180
+ )
181
+
182
+ AWS_PRESERVE_ENV_VARS: Final[frozenset[str]] = frozenset(
183
+ {
184
+ # AWS Core & Authentication
185
+ "AWS_ACCESS_KEY_ID",
186
+ "AWS_SECRET_ACCESS_KEY",
187
+ "AWS_SESSION_TOKEN",
188
+ "AWS_SECURITY_TOKEN",
189
+ "AWS_REGION",
190
+ "AWS_DEFAULT_REGION",
191
+ "AWS_PROFILE",
192
+ "AWS_DEFAULT_PROFILE",
193
+ "AWS_CONFIG_FILE",
194
+ "AWS_SHARED_CREDENTIALS_FILE",
195
+ "AWS_ROLE_ARN",
196
+ "AWS_ROLE_SESSION_NAME",
197
+ "AWS_WEB_IDENTITY_TOKEN_FILE",
198
+ "AWS_STS_REGIONAL_ENDPOINTS",
199
+ "AWS_CA_BUNDLE",
200
+ "AWS_CONTAINER_CREDENTIALS_RELATIVE_URI",
201
+ "AWS_CONTAINER_CREDENTIALS_FULL_URI",
202
+ "AWS_CONTAINER_AUTHORIZATION_TOKEN",
203
+ "AWS_ENDPOINT_URL",
204
+ "AWS_SDK_LOAD_CONFIG",
205
+ "AWS_VAULT",
206
+ "AWS_EC2_METADATA_DISABLED",
207
+ "AWS_MAX_ATTEMPTS",
208
+ "AWS_RETRY_MODE",
209
+ "AWS_APP_NAME",
210
+ "AWS_PAGER",
211
+ # AWS CDK
212
+ "CDK_DEFAULT_ACCOUNT",
213
+ "CDK_DEFAULT_REGION",
214
+ "CDK_DOCKER_DEFAULT_ACCOUNT",
215
+ "CDK_CONTEXT_JSON",
216
+ # AWS SAM
217
+ "SAM_CLI_TELEMETRY",
218
+ # Terraform & OpenTofu
219
+ "TF_IN_AUTOMATION",
220
+ "TF_DATA_DIR",
221
+ "TF_PLUGIN_CACHE_DIR",
222
+ "TF_CLI_CONFIG_FILE",
223
+ # Pulumi
224
+ "PULUMI_CONFIG_PASSPHRASE",
225
+ "PULUMI_ACCESS_TOKEN",
226
+ # Kubernetes / EKS
227
+ "KUBECONFIG",
228
+ "KUBE_NAMESPACE",
229
+ "KUBE_CONTEXT",
230
+ "KUBE_CLUSTER",
231
+ "HELM_CONFIG_HOME",
232
+ "HELM_CACHE_HOME",
233
+ "HELM_DATA_HOME",
234
+ # Docker / ECR
235
+ "DOCKER_HOST",
236
+ "DOCKER_CERT_PATH",
237
+ "DOCKER_TLS_VERIFY",
238
+ }
239
+ )
240
+
241
+ DEVOPS_PRESERVE_ENV_VARS = AWS_PRESERVE_ENV_VARS
242
+
243
+
244
+ # ── Agent / per-agent directory helpers ──────────────────
245
+
246
+ def agent_dir(name: str = DEFAULT_AGENT_NAME) -> Path:
247
+ """Return agent directory.
248
+
249
+ For the default agent ('opscloud'), returns ``~/.opscloud/`` directly.
250
+ For custom named assistants, returns ``~/.opscloud/agents/{name}/``.
251
+ """
252
+ if not name or name == DEFAULT_AGENT_NAME:
253
+ return DATA_DIR
254
+ return DATA_DIR / "agents" / name
255
+
256
+
257
+ def user_skills_dir(name: str = DEFAULT_AGENT_NAME) -> Path:
258
+ """Return ``~/.opscloud/skills/`` for default agent, or ``~/.opscloud/agents/{name}/skills/``."""
259
+ if not name or name == DEFAULT_AGENT_NAME:
260
+ return DATA_DIR / "skills"
261
+ return agent_dir(name) / "skills"
262
+
263
+
264
+ def get_user_skills_dir(name: str = DEFAULT_AGENT_NAME) -> Path:
265
+ """Return user skills directory."""
266
+ return user_skills_dir(name)
267
+
268
+
269
+ def ensure_user_skills_dir(name: str = DEFAULT_AGENT_NAME) -> Path:
270
+ """Create and return user skills directory."""
271
+ d = user_skills_dir(name)
272
+ d.mkdir(parents=True, exist_ok=True)
273
+ return d
274
+
275
+
276
+ def get_built_in_skills_dir() -> Path:
277
+ """Return the directory containing built-in skills packaged with opscloud."""
278
+ return Path(__file__).parent.parent / "built_in_skills"
279
+
280
+
281
+ def get_user_agent_skills_dir() -> Path | None:
282
+ """Return the user's tool-agnostic ``~/.agents/skills`` directory."""
283
+ return AGENTS_SHARED_DIR / "skills"
284
+
285
+
286
+ def get_user_claude_skills_dir() -> Path | None:
287
+ """Return the user's experimental ``~/.claude/skills`` directory."""
288
+ return USER_HOME / ".claude" / "skills"
289
+
290
+
291
+ def user_agents_dir(name: str = DEFAULT_AGENT_NAME) -> Path:
292
+ """Return ``~/.opscloud/agents/`` for default agent, or ``~/.opscloud/agents/{name}/agents/``."""
293
+ if not name or name == DEFAULT_AGENT_NAME:
294
+ return DATA_DIR / "agents"
295
+ return agent_dir(name) / "agents"
296
+
297
+
298
+ DEFAULT_AGENT_MD_TEMPLATE = """# OpsCloud Persistent Memory & Operational Context
299
+
300
+ ## User Preferences & Defaults
301
+ <!-- opscloud:onboarding-name:start -->
302
+ - The user's role/name is "Cloud Platform & DevOps Engineer".
303
+ - Primary Cloud Provider: AWS
304
+ - Default Region: us-east-1
305
+ - IaC Tool Preference: Terraform / OpenTofu
306
+ - Deployment Strategy: Verification first with dry-run before mutation
307
+ <!-- opscloud:onboarding-name:end -->
308
+
309
+ ## Operational Guardrails & Patterns
310
+ - **Dry-Run Validation**: Always execute non-destructive checks (`terraform plan`, `kubectl diff`, `--dry-run=server`) prior to applying infrastructure changes.
311
+ - **Context Hygiene**: Offload high-volume command output and log dumps to files rather than terminal outputs.
312
+ - **Zero-Trust Security**: Apply least-privilege IAM policies and avoid hardcoded credentials or wildcard permissions.
313
+ """
314
+
315
+
316
+ def primary_agent_md() -> Path:
317
+ """Return ``~/.opscloud/AGENTS.md``."""
318
+ return DATA_DIR / "AGENTS.md"
319
+
320
+
321
+ def user_agent_md(name: str = DEFAULT_AGENT_NAME) -> Path:
322
+ """Return ``~/.opscloud/AGENTS.md`` for default agent, or ``~/.opscloud/agents/{name}/AGENTS.md``."""
323
+ if not name or name == DEFAULT_AGENT_NAME:
324
+ return primary_agent_md()
325
+ return agent_dir(name) / "AGENTS.md"
326
+
327
+
328
+ def ensure_user_agent_md(name: str = DEFAULT_AGENT_NAME) -> Path:
329
+ """Ensure ``~/.opscloud/AGENTS.md`` exists on disk.
330
+
331
+ Initializes it with default operational preferences and guardrails if empty or missing.
332
+ For custom named assistants, also initializes the assistant-specific memory file.
333
+
334
+ Returns:
335
+ The primary persistent memory path (``~/.opscloud/AGENTS.md``).
336
+ """
337
+ ensure_data_dir()
338
+ root_md = primary_agent_md()
339
+ if not root_md.exists() or root_md.stat().st_size == 0:
340
+ try:
341
+ root_md.write_text(DEFAULT_AGENT_MD_TEMPLATE, encoding="utf-8")
342
+ except OSError as e:
343
+ logger.warning("Could not write primary memory file %s: %s", root_md, e)
344
+
345
+ if name and name != DEFAULT_AGENT_NAME:
346
+ d = ensure_agent_dir(name)
347
+ agent_md = d / "AGENTS.md"
348
+ if not agent_md.exists() or agent_md.stat().st_size == 0:
349
+ try:
350
+ agent_md.write_text(
351
+ f"# Assistant-Specific Memory: {name}\n\n"
352
+ "<!-- Assistant-specific operational learnings and notes -->\n",
353
+ encoding="utf-8",
354
+ )
355
+ except OSError as e:
356
+ logger.warning("Could not write assistant memory file %s: %s", agent_md, e)
357
+ return root_md
358
+
359
+
360
+ # ── Project directory helpers ────────────────────────────
361
+
362
+ def project_skills_dir(project_root: Path) -> Path:
363
+ """Return ``{project_root}/.opscloud/skills/``."""
364
+ return project_opscloud_dir(project_root) / "skills"
365
+
366
+
367
+ def get_project_skills_dir(project_root: Path | None) -> Path | None:
368
+ """Return the project-level opscloud skills directory, when in a project."""
369
+ return None if project_root is None else project_skills_dir(project_root)
370
+
371
+
372
+ def ensure_project_skills_dir(project_root: Path | None) -> Path | None:
373
+ """Create and return the project-level opscloud skills directory."""
374
+ d = get_project_skills_dir(project_root)
375
+ if d is not None:
376
+ d.mkdir(parents=True, exist_ok=True)
377
+ return d
378
+
379
+
380
+ def get_project_agent_skills_dir(project_root: Path | None) -> Path | None:
381
+ """Return the project's tool-agnostic ``.agents/skills`` directory."""
382
+ return None if project_root is None else project_root / ".agents" / "skills"
383
+
384
+
385
+ def get_project_claude_skills_dir(project_root: Path | None) -> Path | None:
386
+ """Return the project's experimental ``.claude/skills`` directory."""
387
+ return None if project_root is None else project_root / ".claude" / "skills"
388
+
389
+
390
+ def display_path(path: Path | str) -> str:
391
+ """Abbreviate a path for user display with leading ``~`` when under user home."""
392
+ p = Path(path)
393
+ try:
394
+ rel = p.relative_to(USER_HOME)
395
+ return str(Path("~") / rel)
396
+ except (ValueError, RuntimeError):
397
+ return str(path)
398
+
399
+
400
+ class _ProfilePathProxy:
401
+ @staticmethod
402
+ def agent_skills_dir(agent: str) -> Path:
403
+ return user_skills_dir(agent)
404
+
405
+ @property
406
+ def config_file(self) -> Path:
407
+ return CONFIG_PATH
408
+
409
+
410
+ class _PathsSnapshot:
411
+ """Convenience snapshot mirroring dcode PATHS interface for display and paths."""
412
+
413
+ profile = _ProfilePathProxy()
414
+
415
+ @staticmethod
416
+ def display(path: Path | str) -> str:
417
+ return display_path(path)
418
+
419
+
420
+ PATHS = _PathsSnapshot()
421
+
422
+
423
+ def project_agents_dir(project_root: Path) -> Path:
424
+ """Return ``{project_root}/.opscloud/agents/``."""
425
+ return project_opscloud_dir(project_root) / "agents"
426
+
427
+
428
+ def project_mcp_paths(project_root: Path) -> list[Path]:
429
+ """Return candidate MCP config paths for a project, in precedence order."""
430
+ return [
431
+ project_root / ".mcp.json",
432
+ project_root / "mcp.json",
433
+ project_opscloud_dir(project_root) / ".mcp.json",
434
+ project_opscloud_dir(project_root) / "mcp.json",
435
+ ]
436
+
437
+
438
+ def project_agent_md_paths(project_root: Path) -> list[Path]:
439
+ """Return candidate AGENTS.md paths for a project."""
440
+ return [
441
+ project_opscloud_dir(project_root) / "AGENTS.md",
442
+ project_root / "AGENTS.md",
443
+ ]
444
+
445
+
446
+ def find_project_root(start_path: Path | str | None = None) -> Path | None:
447
+ """Climb directories upwards to find project root by well-known marker."""
448
+ if start_path is None:
449
+ try:
450
+ from opscloud.project_utils import get_server_project_context
451
+
452
+ ctx = get_server_project_context()
453
+ if ctx is not None and ctx.project_root is not None:
454
+ return ctx.project_root
455
+ if ctx is not None:
456
+ start_path = ctx.user_cwd
457
+ except Exception:
458
+ pass
459
+
460
+ try:
461
+ curr = Path(start_path or Path.cwd()).resolve()
462
+ except OSError:
463
+ return None
464
+
465
+ home = Path.home().resolve()
466
+ for directory in [curr, *curr.parents]:
467
+ if directory == home:
468
+ continue
469
+ for marker in PROJECT_ROOT_MARKERS:
470
+ if (directory / marker).exists():
471
+ return directory
472
+ return None
473
+
474
+
475
+
476
+ # ── Ensure directories exist ────────────────────────────
477
+
478
+ def ensure_data_dir() -> Path:
479
+ """Create ``~/.opscloud/`` and standard subdirectories if they don't exist."""
480
+ DATA_DIR.mkdir(parents=True, exist_ok=True)
481
+ (DATA_DIR / "skills").mkdir(parents=True, exist_ok=True)
482
+ (DATA_DIR / "agents").mkdir(parents=True, exist_ok=True)
483
+ (DATA_DIR / "memory").mkdir(parents=True, exist_ok=True)
484
+ return DATA_DIR
485
+
486
+
487
+ def ensure_state_dir() -> Path:
488
+ """Create ``~/.opscloud/.state/`` if it doesn't exist."""
489
+ STATE_DIR.mkdir(parents=True, exist_ok=True)
490
+ return STATE_DIR
491
+
492
+
493
+ def ensure_agent_dir(name: str = DEFAULT_AGENT_NAME) -> Path:
494
+ """Create and return agent directory."""
495
+ if not name or name == DEFAULT_AGENT_NAME:
496
+ return ensure_data_dir()
497
+ d = agent_dir(name)
498
+ d.mkdir(parents=True, exist_ok=True)
499
+ return d
500
+
501
+
502
+ def ensure_plugins_dir() -> Path:
503
+ """Create ``~/.opscloud/plugins/`` if it doesn't exist."""
504
+ PLUGINS_DIR.mkdir(parents=True, exist_ok=True)
505
+ return PLUGINS_DIR
506
+
507
+
508
+ def ensure_conversation_history_dir() -> Path:
509
+ """Create ``~/.opscloud/conversation_history/`` if it doesn't exist, restricted to current user."""
510
+ CONVERSATION_HISTORY_DIR.mkdir(parents=True, exist_ok=True)
511
+ try:
512
+ CONVERSATION_HISTORY_DIR.chmod(0o700)
513
+ except OSError:
514
+ pass
515
+ return CONVERSATION_HISTORY_DIR
516
+
517
+
518
+ def upsert_env_vars(env_dict: dict[str, str], env_path: Path | None = None) -> bool:
519
+ """Upsert key-value pairs into a .env file atomically."""
520
+ import contextlib
521
+ import tempfile
522
+
523
+ target_path = env_path or GLOBAL_ENV_PATH
524
+ try:
525
+ target_path.parent.mkdir(parents=True, exist_ok=True)
526
+ lines: list[str] = []
527
+ if target_path.exists():
528
+ content = target_path.read_text(encoding="utf-8")
529
+ lines = content.splitlines()
530
+
531
+ new_lines: list[str] = []
532
+ seen_keys: set[str] = set()
533
+
534
+ for line in lines:
535
+ stripped = line.strip()
536
+ if not stripped or stripped.startswith("#"):
537
+ new_lines.append(line)
538
+ continue
539
+
540
+ raw_key = stripped.removeprefix("export ").split("=", 1)[0].strip()
541
+ if not raw_key:
542
+ new_lines.append(line)
543
+ continue
544
+
545
+ if raw_key in env_dict:
546
+ if raw_key not in seen_keys:
547
+ new_lines.append(f"{raw_key}={env_dict[raw_key]}")
548
+ seen_keys.add(raw_key)
549
+ else:
550
+ if raw_key not in seen_keys:
551
+ new_lines.append(line)
552
+ seen_keys.add(raw_key)
553
+
554
+ for k, v in env_dict.items():
555
+ if k not in seen_keys:
556
+ new_lines.append(f"{k}={v}")
557
+ seen_keys.add(k)
558
+
559
+ final_content = "\n".join(new_lines).strip() + "\n" if new_lines else ""
560
+
561
+ fd, tmp_path = tempfile.mkstemp(dir=target_path.parent, suffix=".tmp")
562
+ try:
563
+ with open(fd, "w", encoding="utf-8") as f:
564
+ f.write(final_content)
565
+ Path(tmp_path).replace(target_path)
566
+ except BaseException:
567
+ with contextlib.suppress(OSError):
568
+ Path(tmp_path).unlink()
569
+ raise
570
+ return True
571
+ except Exception as exc:
572
+ logger.exception("Failed to upsert env vars in %s: %s", target_path, exc)
573
+ return False
574
+
575
+
576
+ # ── Path classification (for doctor/diagnostics) ────────
577
+
578
+ _MISSING_ERRNOS = {errno.ENOENT, errno.ENOTDIR}
579
+
580
+
581
+ class PathState(StrEnum):
582
+ """Whether a probed path exists, is absent, or could not be read."""
583
+
584
+ EXISTS = "exists"
585
+ """The path is present on disk."""
586
+
587
+ MISSING = "missing"
588
+ """The path is absent (and its parents are readable)."""
589
+
590
+ UNREADABLE = "unreadable"
591
+ """Existence could not be determined because ``Path.stat()`` raised."""
592
+
593
+
594
+ def classify_path(path: Path) -> PathState:
595
+ """Classify a path as existing, missing, or unreadable."""
596
+ try:
597
+ path.stat()
598
+ except OSError as exc:
599
+ if exc.errno in _MISSING_ERRNOS:
600
+ return PathState.MISSING
601
+ logger.debug("Could not stat %s", path, exc_info=True)
602
+ return PathState.UNREADABLE
603
+ else:
604
+ return PathState.EXISTS