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,281 @@
1
+ """Service management and plugin state channels for OpsCloud.
2
+
3
+ Provides generic, extensible state contracts for plugins and skills to manage
4
+ live services (containers, clusters, serverless, databases, ingress, networking)
5
+ efficiently across any cloud provider.
6
+
7
+ Allows dynamic plugins to:
8
+ - Register and update managed service targets (health, replicas, status, metrics).
9
+ - Maintain an active service focus for zero-context-switch triage.
10
+ - Record an audit log of operational actions (restarts, scaling, rollouts, patches).
11
+ - Persist plugin-private state across checkpoints without cross-plugin collision.
12
+ """
13
+
14
+ from __future__ import annotations
15
+
16
+ from datetime import datetime, timezone
17
+ from typing import (
18
+ Annotated,
19
+ Any,
20
+ Literal,
21
+ NotRequired,
22
+ TypedDict,
23
+ cast,
24
+ get_args,
25
+ )
26
+
27
+ from langchain.agents.middleware.types import (
28
+ AgentState,
29
+ PrivateStateAttr,
30
+ )
31
+
32
+ ServiceStatus = Literal[
33
+ "healthy",
34
+ "degraded",
35
+ "failing",
36
+ "updating",
37
+ "stopped",
38
+ "unknown",
39
+ ]
40
+ """Lifecycle and health status of a managed cloud service."""
41
+
42
+ _SERVICE_STATUS_VALUES: frozenset[str] = frozenset(get_args(ServiceStatus))
43
+
44
+ ServiceOperationType = Literal[
45
+ "inspect",
46
+ "restart",
47
+ "scale",
48
+ "deploy",
49
+ "rollback",
50
+ "drain",
51
+ "cordon",
52
+ "config_patch",
53
+ "traffic_shift",
54
+ "custom",
55
+ ]
56
+ """Standard operational actions performed on services."""
57
+
58
+
59
+ class ManagedService(TypedDict, total=False):
60
+ """Normalized snapshot of a live managed service."""
61
+
62
+ id: str
63
+ """Unique canonical identifier (e.g. 'k8s:prod/payments' or ECS ARN)."""
64
+
65
+ name: str
66
+ """Human-friendly service name (e.g. 'payments-api')."""
67
+
68
+ provider: str
69
+ """Cloud or platform provider (e.g. 'aws', 'kubernetes', 'azure', 'gcp')."""
70
+
71
+ service_type: str
72
+ """Kind of service (e.g. 'deployment', 'ecs_service', 'rds_database', 'lambda')."""
73
+
74
+ environment: str | None
75
+ """Deployment tier (e.g. 'production', 'staging', 'dev')."""
76
+
77
+ status: ServiceStatus
78
+ """Health/operational status."""
79
+
80
+ health_summary: str | None
81
+ """Brief human-readable health details (e.g. '3/3 pods ready, 0 restarts')."""
82
+
83
+ metrics_summary: str | None
84
+ """Key operational metrics (e.g. 'p99: 45ms, error_rate: 0.02%')."""
85
+
86
+ last_action: str | None
87
+ """Last action taken on this service (e.g. 'scaled replicas to 5')."""
88
+
89
+ updated_at: str
90
+ """ISO timestamp of last update."""
91
+
92
+ metadata: dict[str, Any]
93
+ """Plugin-extensible arbitrary metadata (cluster, namespace, image, port, etc.)."""
94
+
95
+
96
+ class ServiceOperationRecord(TypedDict):
97
+ """Audit record of an operational action executed on a managed service."""
98
+
99
+ operation_id: str
100
+ service_id: str
101
+ action: ServiceOperationType | str
102
+ status: Literal["started", "succeeded", "failed", "pending_approval"]
103
+ details: str
104
+ initiated_by: str
105
+ timestamp: str
106
+
107
+
108
+ def _merge_managed_services(
109
+ existing: dict[str, ManagedService] | None,
110
+ new: dict[str, ManagedService] | None,
111
+ ) -> dict[str, ManagedService]:
112
+ """Reducer that merges managed services by service ID, updating changed fields."""
113
+ if not existing:
114
+ return dict(new or {})
115
+ if not new:
116
+ return dict(existing)
117
+
118
+ merged = dict(existing)
119
+ for service_id, new_svc in new.items():
120
+ if service_id in merged:
121
+ current = dict(merged[service_id])
122
+ current.update(new_svc)
123
+ merged[service_id] = cast(ManagedService, current)
124
+ else:
125
+ merged[service_id] = new_svc
126
+ return merged
127
+
128
+
129
+ def _merge_operations_log(
130
+ existing: list[ServiceOperationRecord] | None,
131
+ new: list[ServiceOperationRecord] | None,
132
+ ) -> list[ServiceOperationRecord]:
133
+ """Accumulating reducer that appends service operations in chronological order."""
134
+ if not existing:
135
+ return list(new or [])
136
+ if not new:
137
+ return list(existing)
138
+
139
+ seen_ids = {op["operation_id"] for op in existing}
140
+ result = list(existing)
141
+ for op in new:
142
+ if op["operation_id"] not in seen_ids:
143
+ seen_ids.add(op["operation_id"])
144
+ result.append(op)
145
+ return result
146
+
147
+
148
+ def _merge_plugin_state(
149
+ existing: dict[str, Any] | None,
150
+ new: dict[str, Any] | None,
151
+ ) -> dict[str, Any]:
152
+ """Reducer that deep-merges plugin-scoped namespaces without cross-plugin clobbering."""
153
+ if not existing:
154
+ return dict(new or {})
155
+ if not new:
156
+ return dict(existing)
157
+
158
+ merged = dict(existing)
159
+ for plugin_name, plugin_data in new.items():
160
+ if isinstance(plugin_data, dict) and isinstance(merged.get(plugin_name), dict):
161
+ merged[plugin_name] = {**merged[plugin_name], **plugin_data}
162
+ else:
163
+ merged[plugin_name] = plugin_data
164
+ return merged
165
+
166
+
167
+ def _merge_unique_strings(
168
+ existing: list[str] | None,
169
+ new: list[str] | None,
170
+ ) -> list[str]:
171
+ """Reducer that accumulates unique string names preserving order."""
172
+ if not existing:
173
+ return list(new or [])
174
+ if not new:
175
+ return list(existing)
176
+ seen = set(existing)
177
+ result = list(existing)
178
+ for item in new:
179
+ if item not in seen:
180
+ seen.add(item)
181
+ result.append(item)
182
+ return result
183
+
184
+
185
+ def make_service_record(
186
+ id: str,
187
+ name: str,
188
+ provider: str,
189
+ service_type: str,
190
+ *,
191
+ environment: str | None = None,
192
+ status: ServiceStatus = "unknown",
193
+ health_summary: str | None = None,
194
+ metrics_summary: str | None = None,
195
+ last_action: str | None = None,
196
+ metadata: dict[str, Any] | None = None,
197
+ ) -> ManagedService:
198
+ """Helper to construct a validated ManagedService instance."""
199
+ return {
200
+ "id": id,
201
+ "name": name,
202
+ "provider": provider,
203
+ "service_type": service_type,
204
+ "environment": environment,
205
+ "status": status if status in _SERVICE_STATUS_VALUES else "unknown",
206
+ "health_summary": health_summary,
207
+ "metrics_summary": metrics_summary,
208
+ "last_action": last_action,
209
+ "updated_at": datetime.now(timezone.utc).isoformat(),
210
+ "metadata": dict(metadata or {}),
211
+ }
212
+
213
+
214
+ def make_operation_record(
215
+ operation_id: str,
216
+ service_id: str,
217
+ action: ServiceOperationType | str,
218
+ *,
219
+ status: Literal["started", "succeeded", "failed", "pending_approval"] = "succeeded",
220
+ details: str = "",
221
+ initiated_by: str = "agent",
222
+ ) -> ServiceOperationRecord:
223
+ """Helper to construct a ServiceOperationRecord."""
224
+ return {
225
+ "operation_id": operation_id,
226
+ "service_id": service_id,
227
+ "action": action,
228
+ "status": status,
229
+ "details": details,
230
+ "initiated_by": initiated_by,
231
+ "timestamp": datetime.now(timezone.utc).isoformat(),
232
+ }
233
+
234
+
235
+ class ServiceContextState(AgentState):
236
+ """State channels for managing live cloud services and plugin runtimes."""
237
+
238
+ _managed_services: Annotated[
239
+ NotRequired[dict[str, ManagedService]],
240
+ PrivateStateAttr,
241
+ _merge_managed_services,
242
+ ]
243
+ """Registry of live cloud services currently managed, monitored, or inspected."""
244
+
245
+ _active_service_id: Annotated[
246
+ NotRequired[str | None],
247
+ PrivateStateAttr,
248
+ ]
249
+ """ID of the service currently in focus for troubleshooting or operational commands."""
250
+
251
+ _service_operations_log: Annotated[
252
+ NotRequired[list[ServiceOperationRecord]],
253
+ PrivateStateAttr,
254
+ _merge_operations_log,
255
+ ]
256
+ """Chronological audit log of operations performed on services in this thread."""
257
+
258
+ _plugin_state: Annotated[
259
+ NotRequired[dict[str, Any]],
260
+ PrivateStateAttr,
261
+ _merge_plugin_state,
262
+ ]
263
+ """Extensible namespace for plugins to store private checkpointed state."""
264
+
265
+ _active_plugins: Annotated[
266
+ NotRequired[list[str]],
267
+ PrivateStateAttr,
268
+ _merge_unique_strings,
269
+ ]
270
+ """Names of active plugins enabled in the current thread."""
271
+
272
+
273
+ __all__ = [
274
+ "ManagedService",
275
+ "ServiceContextState",
276
+ "ServiceOperationRecord",
277
+ "ServiceOperationType",
278
+ "ServiceStatus",
279
+ "make_operation_record",
280
+ "make_service_record",
281
+ ]