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,91 @@
1
+ """Security policies, approval modes, and AST command safety evaluators for OpsCloud."""
2
+
3
+ from opscloud.security.approval_mode import (
4
+ APPROVAL_MODE_NAMESPACE,
5
+ ApprovalMode,
6
+ approval_mode_key,
7
+ approval_mode_scope,
8
+ coerce_approval_mode,
9
+ get_approval_mode,
10
+ next_approval_mode,
11
+ set_approval_mode,
12
+ )
13
+ from opscloud.security.approval_mode_source import (
14
+ ApprovalPolicyResolver,
15
+ _DecidedMode,
16
+ _LiveLookup,
17
+ _approval_mode_source,
18
+ _aresolve_approval_mode,
19
+ _resolve_approval_mode,
20
+ )
21
+ from opscloud.security.cli_ast_evaluator import (
22
+ DANGEROUS_FLAGS,
23
+ DANGEROUS_VERBS,
24
+ READONLY_UTILITIES,
25
+ READONLY_VERBS,
26
+ SecurityASTVisitor,
27
+ WRAPPER_UTILITIES,
28
+ evaluate_cli_safety,
29
+ )
30
+ from opscloud.security.shell_safety import (
31
+ AWS_DANGEROUS_PATTERNS,
32
+ AWS_SAFE_COMMANDS,
33
+ CLOUD_DANGEROUS_PATTERNS,
34
+ CLOUD_SAFE_COMMANDS,
35
+ DANGEROUS_SHELL_PATTERNS,
36
+ DEVOPS_DESTRUCTIVE_COMMANDS,
37
+ DEVOPS_SAFE_COMMANDS,
38
+ classify_command,
39
+ is_safe_command,
40
+ )
41
+ from opscloud.security.unicode_security import (
42
+ CONFUSABLES,
43
+ UnicodeSanitizeResult,
44
+ normalize_confusables,
45
+ sanitize_unicode,
46
+ )
47
+ from opscloud.security.url_validation import (
48
+ UrlValidationError,
49
+ is_url_safe,
50
+ validate_url,
51
+ )
52
+
53
+ __all__ = [
54
+ "APPROVAL_MODE_NAMESPACE",
55
+ "AWS_DANGEROUS_PATTERNS",
56
+ "AWS_SAFE_COMMANDS",
57
+ "ApprovalMode",
58
+ "ApprovalPolicyResolver",
59
+ "CLOUD_DANGEROUS_PATTERNS",
60
+ "CLOUD_SAFE_COMMANDS",
61
+ "CONFUSABLES",
62
+ "DANGEROUS_FLAGS",
63
+ "DANGEROUS_SHELL_PATTERNS",
64
+ "DANGEROUS_VERBS",
65
+ "DEVOPS_DESTRUCTIVE_COMMANDS",
66
+ "DEVOPS_SAFE_COMMANDS",
67
+ "READONLY_UTILITIES",
68
+ "READONLY_VERBS",
69
+ "SecurityASTVisitor",
70
+ "UnicodeSanitizeResult",
71
+ "UrlValidationError",
72
+ "WRAPPER_UTILITIES",
73
+ "_DecidedMode",
74
+ "_LiveLookup",
75
+ "_approval_mode_source",
76
+ "_aresolve_approval_mode",
77
+ "_resolve_approval_mode",
78
+ "approval_mode_key",
79
+ "approval_mode_scope",
80
+ "classify_command",
81
+ "coerce_approval_mode",
82
+ "evaluate_cli_safety",
83
+ "get_approval_mode",
84
+ "is_safe_command",
85
+ "is_url_safe",
86
+ "next_approval_mode",
87
+ "normalize_confusables",
88
+ "sanitize_unicode",
89
+ "set_approval_mode",
90
+ "validate_url",
91
+ ]
@@ -0,0 +1,528 @@
1
+ """Approval-mode state shared by clients, server, and middleware in OpsCloud.
2
+
3
+ Aligned with official dcode contracts and tailored for OpsCloud terminal operations.
4
+ """
5
+
6
+ from __future__ import annotations
7
+
8
+ import asyncio
9
+ from collections.abc import Generator, Mapping
10
+ import contextlib
11
+ from contextlib import contextmanager
12
+ from enum import StrEnum
13
+ import inspect
14
+ import json
15
+ import os
16
+ from pathlib import Path
17
+ import tempfile
18
+ import threading
19
+ from typing import Any, TypedDict
20
+
21
+ from filelock import FileLock, Timeout
22
+
23
+ from opscloud.config.paths import STATE_DIR
24
+ from opscloud.utils.logger import get_logger
25
+
26
+ logger = get_logger(__name__)
27
+
28
+ APPROVAL_MODE_NAMESPACE: tuple[str, str] = ("opscloud", "approval_mode")
29
+ """Store namespace for per-thread approval-mode control records."""
30
+
31
+ AUTO_NOTICE_VERSION = "2026-08-23"
32
+
33
+
34
+ class ApprovalMode(StrEnum):
35
+ """Tool-approval policy selected for an interactive thread.
36
+
37
+ - MANUAL: Prompt human for confirmation on risky or mutating actions (safe default).
38
+ - AUTO: Classic agent LLM classifier decides (uses primary reasoning model).
39
+ - SMART: Jev System One classifier decides (ultra-fast <100ms, calibrated risk probabilities).
40
+ """
41
+
42
+ MANUAL = "manual"
43
+ AUTO = "auto"
44
+ SMART = "smart"
45
+
46
+ # Compatibility alias
47
+ ALWAYS = "manual"
48
+
49
+ @classmethod
50
+ def from_str(cls, value: str | None) -> ApprovalMode:
51
+ """Parse string to ApprovalMode, failing closed to MANUAL."""
52
+ return coerce_approval_mode(value)
53
+
54
+
55
+ class ApprovalModePayload(TypedDict):
56
+ """Stored approval-mode control payload."""
57
+
58
+ mode: str
59
+
60
+
61
+ def coerce_approval_mode(value: object) -> ApprovalMode:
62
+ """Return a validated mode, failing closed to `MANUAL`."""
63
+ if isinstance(value, bool):
64
+ return ApprovalMode.AUTO if value else ApprovalMode.MANUAL
65
+ if value is None:
66
+ return ApprovalMode.MANUAL
67
+ if isinstance(value, ApprovalMode):
68
+ return value
69
+ if isinstance(value, str):
70
+ normalized = value.strip().lower()
71
+ if normalized in {"manual", "m", "always"}:
72
+ return ApprovalMode.MANUAL
73
+ if normalized in {"auto", "a"}:
74
+ return ApprovalMode.AUTO
75
+ if normalized in {"smart", "s", "jev"}:
76
+ return ApprovalMode.SMART
77
+ return ApprovalMode.MANUAL
78
+
79
+
80
+ def approval_mode_payload(
81
+ *,
82
+ mode: ApprovalMode | str | None = None,
83
+ auto_approve: bool | None = None,
84
+ ) -> ApprovalModePayload:
85
+ """Return the stored approval-mode payload.
86
+
87
+ Args:
88
+ mode: Explicit approval mode.
89
+ auto_approve: Compatibility input for callers using previous Boolean API.
90
+ `True` maps to `auto`, and `False` maps to `manual`.
91
+
92
+ Returns:
93
+ JSON-serializable store value.
94
+
95
+ Raises:
96
+ ValueError: If neither or both inputs are supplied, or `mode` is invalid.
97
+ """
98
+ if (mode is None) == (auto_approve is None):
99
+ msg = "Provide exactly one of mode or auto_approve"
100
+ raise ValueError(msg)
101
+ if auto_approve is not None:
102
+ resolved = ApprovalMode.AUTO if auto_approve else ApprovalMode.MANUAL
103
+ else:
104
+ resolved = coerce_approval_mode(mode)
105
+ return {"mode": resolved.value}
106
+
107
+
108
+ def next_approval_mode(
109
+ current: ApprovalMode | str | object,
110
+ *,
111
+ auto_eligible: bool = True,
112
+ smart_eligible: bool = True,
113
+ ) -> ApprovalMode:
114
+ """Cycle to the next approval mode (Manual → Auto → Smart → Manual).
115
+
116
+ Used by the Textual TUI (`Shift+Tab` switcher) and CLI interactive cycles.
117
+ """
118
+ mode = current if isinstance(current, ApprovalMode) else coerce_approval_mode(current)
119
+
120
+ if mode == ApprovalMode.MANUAL:
121
+ if auto_eligible:
122
+ return ApprovalMode.AUTO
123
+ if smart_eligible:
124
+ return ApprovalMode.SMART
125
+ return ApprovalMode.MANUAL
126
+
127
+ if mode == ApprovalMode.AUTO:
128
+ if smart_eligible:
129
+ return ApprovalMode.SMART
130
+ return ApprovalMode.MANUAL
131
+
132
+ if mode == ApprovalMode.SMART:
133
+ return ApprovalMode.MANUAL
134
+
135
+ return ApprovalMode.MANUAL
136
+
137
+
138
+ def approval_mode_key(thread_id: str) -> str:
139
+ """Derive the canonical Store key for a thread's approval mode."""
140
+ return f"thread:{thread_id}:mode"
141
+
142
+
143
+ def _item_value(item: object) -> object:
144
+ """Extract a store item's value."""
145
+ if isinstance(item, Mapping):
146
+ return item.get("value")
147
+ return getattr(item, "value", None)
148
+
149
+
150
+ def _approval_mode_from_item(item: object) -> ApprovalMode | None:
151
+ """Extract a validated approval mode from a Store item."""
152
+ if item is None:
153
+ logger.debug("Approval-mode store item is missing")
154
+ return None
155
+
156
+ value = _item_value(item)
157
+ raw_mode = value.get("mode") if isinstance(value, Mapping) else None
158
+ if isinstance(raw_mode, str):
159
+ try:
160
+ return ApprovalMode(raw_mode)
161
+ except ValueError:
162
+ pass
163
+
164
+ logger.warning("Approval-mode store item has invalid contents")
165
+ return None
166
+
167
+
168
+ def read_approval_mode_from_store(
169
+ store: object, key: str | None
170
+ ) -> ApprovalMode | None:
171
+ """Read a live approval mode from the server-side LangGraph Store.
172
+
173
+ Args:
174
+ store: `request.runtime.store` from the graph server.
175
+ key: Store key produced by `approval_mode_key`.
176
+
177
+ Returns:
178
+ A validated mode, or `None` when the record cannot be trusted. Callers
179
+ must interpret `None` as `manual`.
180
+ """
181
+ if store is None:
182
+ logger.debug("Approval-mode store is unavailable")
183
+ return None
184
+ if not isinstance(key, str) or not key:
185
+ logger.debug("Approval-mode store key is missing or invalid")
186
+ return None
187
+
188
+ get = getattr(store, "get", None)
189
+ if get is None:
190
+ logger.debug("Approval-mode store does not expose get()")
191
+ return None
192
+
193
+ try:
194
+ item = get(APPROVAL_MODE_NAMESPACE, key)
195
+ except asyncio.InvalidStateError as exc:
196
+ logger.debug(
197
+ "Synchronous store.get() rejected on event loop (%s): %s",
198
+ type(store).__name__,
199
+ exc,
200
+ )
201
+ return None
202
+ except Exception:
203
+ logger.warning("Could not read approval-mode store item", exc_info=True)
204
+ return None
205
+ return _approval_mode_from_item(item)
206
+
207
+
208
+ async def aread_approval_mode_from_store(
209
+ store: object, key: str | None
210
+ ) -> ApprovalMode | None:
211
+ """Asynchronously read a live approval mode from a LangGraph Store.
212
+
213
+ Args:
214
+ store: `request.runtime.store` from the graph server.
215
+ key: Store key produced by `approval_mode_key`.
216
+
217
+ Returns:
218
+ A validated mode, or `None` when the record cannot be trusted. Callers
219
+ must interpret `None` as `manual`.
220
+ """
221
+ if store is None:
222
+ logger.debug("Approval-mode store is unavailable")
223
+ return None
224
+ if not isinstance(key, str) or not key:
225
+ logger.debug("Approval-mode store key is missing or invalid")
226
+ return None
227
+
228
+ aget = getattr(store, "aget", None)
229
+ get = getattr(store, "get", None)
230
+ try:
231
+ if callable(aget):
232
+ result = aget(APPROVAL_MODE_NAMESPACE, key)
233
+ item = await result if inspect.isawaitable(result) else result
234
+ elif callable(get):
235
+ item = get(APPROVAL_MODE_NAMESPACE, key)
236
+ else:
237
+ logger.debug("Approval-mode store does not expose get() or aget()")
238
+ return None
239
+ except asyncio.InvalidStateError as exc:
240
+ logger.debug("Asynchronous store access rejected: %s", exc)
241
+ return None
242
+ except Exception:
243
+ logger.warning("Could not read approval-mode store item", exc_info=True)
244
+ return None
245
+ return _approval_mode_from_item(item)
246
+
247
+
248
+ async def awrite_approval_mode(
249
+ agent: object,
250
+ thread_id: str,
251
+ *,
252
+ mode: ApprovalMode | str | None = None,
253
+ auto_approve: bool | None = None,
254
+ ) -> str | None:
255
+ """Persist approval mode through an agent's remote store client or attached store.
256
+
257
+ Args:
258
+ agent: Agent object (remote agent or client exposing `aput_store_item`, or object with `.store`).
259
+ thread_id: LangGraph thread id for the active session.
260
+ mode: Explicit approval mode.
261
+ auto_approve: Compatibility input for the previous Boolean API.
262
+
263
+ Returns:
264
+ Store key written, or `None` when the agent has no store writer.
265
+ """
266
+ key = approval_mode_key(thread_id)
267
+ try:
268
+ payload = approval_mode_payload(mode=mode, auto_approve=auto_approve)
269
+ except Exception:
270
+ logger.debug("Failed to construct approval mode payload", exc_info=True)
271
+ return None
272
+
273
+ # Synchronize in-memory fallback state
274
+ resolved = coerce_approval_mode(payload.get("mode"))
275
+ set_approval_mode(thread_id, resolved)
276
+
277
+ written = False
278
+
279
+ # 1. Agent exposes direct aput_store_item (e.g. RemoteAgent)
280
+ put = getattr(agent, "aput_store_item", None)
281
+ if callable(put):
282
+ try:
283
+ result = put(APPROVAL_MODE_NAMESPACE, key, payload)
284
+ if inspect.isawaitable(result):
285
+ await result
286
+ written = True
287
+ except Exception:
288
+ logger.debug("Failed to write approval mode via agent.aput_store_item", exc_info=True)
289
+
290
+ # 2. Agent exposes store or agent itself is a store
291
+ if not written:
292
+ store = getattr(agent, "store", None)
293
+ if store is None and any(callable(getattr(agent, attr, None)) for attr in ("put_item", "aput", "put")):
294
+ store = agent
295
+
296
+ if store is not None:
297
+ try:
298
+ put_item_fn = getattr(store, "put_item", None)
299
+ aput_fn = getattr(store, "aput", None)
300
+ put_fn = getattr(store, "put", None)
301
+
302
+ if callable(put_item_fn):
303
+ res = put_item_fn(APPROVAL_MODE_NAMESPACE, key, payload, index=False)
304
+ if inspect.isawaitable(res):
305
+ await res
306
+ written = True
307
+ elif callable(aput_fn):
308
+ res = aput_fn(APPROVAL_MODE_NAMESPACE, key, payload)
309
+ if inspect.isawaitable(res):
310
+ await res
311
+ written = True
312
+ elif callable(put_fn):
313
+ res = put_fn(APPROVAL_MODE_NAMESPACE, key, payload)
314
+ if inspect.isawaitable(res):
315
+ await res
316
+ written = True
317
+ except Exception:
318
+ logger.debug("Failed to write approval mode via agent.store", exc_info=True)
319
+
320
+ return key
321
+
322
+
323
+ _IN_MEMORY_MODES: dict[str, ApprovalMode] = {}
324
+
325
+
326
+ def get_approval_mode(thread_id: str | None = None) -> ApprovalMode:
327
+ """Retrieve current approval mode for thread, failing closed to MANUAL."""
328
+ if not thread_id:
329
+ return ApprovalMode.MANUAL
330
+ return _IN_MEMORY_MODES.get(thread_id, ApprovalMode.MANUAL)
331
+
332
+
333
+ def set_approval_mode(thread_id: str, mode: ApprovalMode | str) -> ApprovalMode:
334
+ """Persist updated approval mode for thread in memory."""
335
+ resolved = coerce_approval_mode(mode)
336
+ _IN_MEMORY_MODES[thread_id] = resolved
337
+ return resolved
338
+
339
+
340
+ @contextmanager
341
+ def approval_mode_scope(thread_id: str, mode: ApprovalMode | str) -> Generator[ApprovalMode, None, None]:
342
+ """Temporarily override approval mode within a context manager block."""
343
+ prev = get_approval_mode(thread_id)
344
+ new_mode = set_approval_mode(thread_id, mode)
345
+ try:
346
+ yield new_mode
347
+ finally:
348
+ set_approval_mode(thread_id, prev)
349
+
350
+
351
+ _APPROVAL_STATE_LOCK_TIMEOUT_SECONDS = 5.0
352
+ """Longest a save waits for the shared install-local approval-state lock."""
353
+
354
+ _APPROVAL_STATE_THREAD_LOCKS: dict[str, threading.Lock] = {}
355
+ _APPROVAL_STATE_THREAD_LOCKS_GUARD = threading.Lock()
356
+
357
+
358
+ def approval_state_path() -> Path:
359
+ """Return the installation-local approval state file path.
360
+
361
+ Returns:
362
+ Path under the private opscloud state directory.
363
+ """
364
+ return STATE_DIR / "approval.json"
365
+
366
+
367
+ def _approval_state_lock_path(path: Path) -> Path:
368
+ """Return the sibling lock file path that serializes approval-state saves."""
369
+ return path.with_name(f"{path.name}.lock")
370
+
371
+
372
+ def _approval_state_thread_lock(path: Path) -> threading.Lock:
373
+ """Return the process-local mutation lock for an approval-state path."""
374
+ key = str(path)
375
+ with _APPROVAL_STATE_THREAD_LOCKS_GUARD:
376
+ lock = _APPROVAL_STATE_THREAD_LOCKS.get(key)
377
+ if lock is None:
378
+ lock = threading.Lock()
379
+ _APPROVAL_STATE_THREAD_LOCKS[key] = lock
380
+ return lock
381
+
382
+
383
+ @contextmanager
384
+ def _approval_state_lock(path: Path) -> Generator[None, None, None]:
385
+ """Serialize read-merge-write updates to install-local approval state."""
386
+ path.parent.mkdir(parents=True, exist_ok=True, mode=0o700)
387
+ if os.name != "nt":
388
+ path.parent.chmod(0o700)
389
+ file_lock = FileLock(
390
+ str(_approval_state_lock_path(path)),
391
+ timeout=_APPROVAL_STATE_LOCK_TIMEOUT_SECONDS,
392
+ thread_local=False,
393
+ )
394
+ with _approval_state_thread_lock(path), file_lock:
395
+ yield
396
+
397
+
398
+ def _load_approval_state(path: Path) -> dict[str, object]:
399
+ """Load the install-local approval state file, or an empty dict."""
400
+ try:
401
+ data = json.loads(path.read_text(encoding="utf-8"))
402
+ except FileNotFoundError:
403
+ return {}
404
+ except (OSError, UnicodeDecodeError, json.JSONDecodeError):
405
+ logger.warning(
406
+ "Ignoring unreadable or corrupt approval state at %s; callers fail "
407
+ "closed and the file will be overwritten on the next save",
408
+ path,
409
+ exc_info=True,
410
+ )
411
+ return {}
412
+ if not isinstance(data, dict):
413
+ logger.warning(
414
+ "Ignoring non-object approval state at %s; callers fail closed and "
415
+ "the file will be overwritten on the next save",
416
+ path,
417
+ )
418
+ return {}
419
+ return data
420
+
421
+
422
+ def _write_approval_state(
423
+ path: Path,
424
+ payload: Mapping[str, object],
425
+ *,
426
+ failure_label: str,
427
+ ) -> bool:
428
+ """Atomically write install-local approval state."""
429
+ tmp_path: Path | None = None
430
+ try:
431
+ path.parent.mkdir(parents=True, exist_ok=True, mode=0o700)
432
+ if os.name != "nt":
433
+ path.parent.chmod(0o700)
434
+ fd, raw_tmp_path = tempfile.mkstemp(dir=path.parent, suffix=".tmp")
435
+ tmp_path = Path(raw_tmp_path)
436
+ with os.fdopen(fd, "w", encoding="utf-8") as handle:
437
+ json.dump(payload, handle, separators=(",", ":"))
438
+ handle.write("\n")
439
+ if os.name != "nt":
440
+ tmp_path.chmod(0o600)
441
+ tmp_path.replace(path)
442
+ if os.name != "nt":
443
+ path.chmod(0o600)
444
+ except OSError:
445
+ logger.warning("Could not persist %s", failure_label, exc_info=True)
446
+ if tmp_path is not None:
447
+ with contextlib.suppress(OSError):
448
+ tmp_path.unlink()
449
+ return False
450
+ return True
451
+
452
+
453
+ def _merge_approval_state(
454
+ path: Path,
455
+ updates: Mapping[str, object],
456
+ *,
457
+ failure_label: str,
458
+ ) -> bool:
459
+ """Load, merge, and write install-local approval state under a lock."""
460
+ try:
461
+ with _approval_state_lock(path):
462
+ payload = {
463
+ **_load_approval_state(path),
464
+ **updates,
465
+ "version": 1,
466
+ }
467
+ return _write_approval_state(
468
+ path,
469
+ payload,
470
+ failure_label=failure_label,
471
+ )
472
+ except Timeout:
473
+ logger.warning(
474
+ "Timed out waiting to persist %s",
475
+ failure_label,
476
+ exc_info=True,
477
+ )
478
+ return False
479
+ except OSError:
480
+ logger.warning(
481
+ "Could not lock approval state for %s", failure_label, exc_info=True
482
+ )
483
+ return False
484
+
485
+
486
+ def has_auto_mode_notice(path: Path | None = None) -> bool:
487
+ """Return whether the current Auto first-enable notice was already shown."""
488
+ target = path or approval_state_path()
489
+ data = _load_approval_state(target)
490
+ return (
491
+ data.get("auto_notice_shown") is True
492
+ and data.get("auto_notice_version") == AUTO_NOTICE_VERSION
493
+ )
494
+
495
+
496
+ def save_auto_mode_notice(path: Path | None = None) -> bool:
497
+ """Persist that the Auto first-enable notice was shown."""
498
+ target = path or approval_state_path()
499
+ return _merge_approval_state(
500
+ target,
501
+ {
502
+ "auto_notice_version": AUTO_NOTICE_VERSION,
503
+ "auto_notice_shown": True,
504
+ },
505
+ failure_label="Auto mode notice",
506
+ )
507
+
508
+
509
+ __all__ = [
510
+ "APPROVAL_MODE_NAMESPACE",
511
+ "AUTO_NOTICE_VERSION",
512
+ "ApprovalMode",
513
+ "ApprovalModePayload",
514
+ "approval_mode_key",
515
+ "approval_mode_payload",
516
+ "approval_mode_scope",
517
+ "approval_state_path",
518
+ "aread_approval_mode_from_store",
519
+ "awrite_approval_mode",
520
+ "coerce_approval_mode",
521
+ "get_approval_mode",
522
+ "has_auto_mode_notice",
523
+ "next_approval_mode",
524
+ "read_approval_mode_from_store",
525
+ "save_auto_mode_notice",
526
+ "set_approval_mode",
527
+ ]
528
+