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,434 @@
1
+ """Domain models for hook lifecycle invocations and decisions."""
2
+
3
+ from __future__ import annotations
4
+
5
+ from enum import StrEnum
6
+ from pathlib import Path
7
+ from typing import TYPE_CHECKING, Annotated, Any, Literal, cast
8
+ from uuid import UUID
9
+
10
+ from langchain_core.messages import ToolMessage
11
+ from pydantic import BaseModel, ConfigDict, Field
12
+
13
+ from opscloud.json_types import JSON_VALUE_ADAPTER, JsonObject, JsonValue
14
+ from opscloud.security.approval_mode import ApprovalMode
15
+
16
+ if TYPE_CHECKING:
17
+ from langgraph.types import Command
18
+
19
+
20
+ class _DomainModel(BaseModel):
21
+ """Base model for hook domain objects with common serialization."""
22
+
23
+ model_config = ConfigDict(extra="forbid", arbitrary_types_allowed=True)
24
+
25
+
26
+ class HookEvent(StrEnum):
27
+ """Supported hook lifecycle events."""
28
+
29
+ SESSION_START = "SessionStart"
30
+ USER_PROMPT_SUBMIT = "UserPromptSubmit"
31
+ SESSION_END = "SessionEnd"
32
+ PERMISSION_REQUEST = "PermissionRequest"
33
+ NOTIFICATION = "Notification"
34
+ PRE_TOOL_USE = "PreToolUse"
35
+ POST_TOOL_USE = "PostToolUse"
36
+ POST_TOOL_USE_FAILURE = "PostToolUseFailure"
37
+ PRE_COMPACT = "PreCompact"
38
+ STOP = "Stop"
39
+ SUBAGENT_START = "SubagentStart"
40
+ SUBAGENT_STOP = "SubagentStop"
41
+
42
+
43
+ class HookOwner(StrEnum):
44
+ """Process responsible for originating an event."""
45
+
46
+ CLIENT = "client"
47
+ SERVER = "server"
48
+
49
+
50
+ class SessionStartCause(StrEnum):
51
+ """Reason a session-start event occurred."""
52
+
53
+ STARTUP = "startup"
54
+ RESUME = "resume"
55
+ CLEAR = "clear"
56
+ COMPACT = "compact"
57
+
58
+
59
+ class SessionEndCause(StrEnum):
60
+ """Reason a session-end event occurred."""
61
+
62
+ CLEAR = "clear"
63
+ RESUME = "resume"
64
+ LOGOUT = "logout"
65
+ PROMPT_INPUT_EXIT = "prompt_input_exit"
66
+ BYPASS_PERMISSIONS_DISABLED = "bypass_permissions_disabled"
67
+ OTHER = "other"
68
+
69
+
70
+ class OpscloudNotificationKind(StrEnum):
71
+ """OpsCloud lifecycle notifications with compatible wire mappings."""
72
+
73
+ PERMISSION_REQUIRED = "permission_required"
74
+ AGENT_NEEDS_INPUT = "agent_needs_input"
75
+ AGENT_COMPLETED = "agent_completed"
76
+
77
+
78
+ class CompactTrigger(StrEnum):
79
+ """Reason context compaction was requested."""
80
+
81
+ MANUAL = "manual"
82
+ AUTO = "auto"
83
+
84
+
85
+ type EffortLevel = Literal["none", "low", "medium", "high", "xhigh", "max"]
86
+
87
+
88
+ class ToolCallData(_DomainModel):
89
+ """Native tool-call data used by hook lifecycle owners."""
90
+
91
+ id: str
92
+ name: str
93
+ args: JsonObject
94
+ mcp_server: str | None = None
95
+
96
+
97
+ class AgentIdentity(_DomainModel):
98
+ """Resolved subagent identity."""
99
+
100
+ id: str
101
+ name: str
102
+
103
+
104
+ class OpscloudNotification(_DomainModel):
105
+ """A notification emitted by an OpsCloud lifecycle owner."""
106
+
107
+ type: str
108
+ message: str
109
+ title: str | None = None
110
+
111
+
112
+ class BackgroundTaskSnapshot(_DomainModel):
113
+ """Background task state captured for a hook invocation."""
114
+
115
+ id: str
116
+ type: str
117
+ status: str
118
+ description: str
119
+ command: str | None = None
120
+ agent_type: str | None = None
121
+ server: str | None = None
122
+ tool: str | None = None
123
+ name: str | None = None
124
+
125
+
126
+ class SessionCronSnapshot(_DomainModel):
127
+ """Scheduled session prompt captured for a hook invocation."""
128
+
129
+ id: str
130
+ schedule: str
131
+ recurring: bool
132
+ prompt: str
133
+
134
+
135
+ class HookContext(_DomainModel):
136
+ """Context shared by every domain hook event."""
137
+
138
+ thread_id: str
139
+ cwd: Path
140
+ prompt_id: UUID | None = None
141
+ approval_mode: ApprovalMode
142
+ effort: EffortLevel | None = None
143
+ agent: AgentIdentity | None = None
144
+ transcript_revision: str | None = None
145
+
146
+
147
+ class SessionStartEvent(_DomainModel):
148
+ """Domain payload for `SessionStart`."""
149
+
150
+ event: Literal[HookEvent.SESSION_START]
151
+ cause: SessionStartCause
152
+ model: str | None = None
153
+
154
+
155
+ class UserPromptSubmitEvent(_DomainModel):
156
+ """Domain payload for `UserPromptSubmit`."""
157
+
158
+ event: Literal[HookEvent.USER_PROMPT_SUBMIT]
159
+ prompt: str
160
+
161
+
162
+ class SessionEndEvent(_DomainModel):
163
+ """Domain payload for `SessionEnd`."""
164
+
165
+ event: Literal[HookEvent.SESSION_END]
166
+ cause: SessionEndCause
167
+
168
+
169
+ class PermissionRequestEvent(_DomainModel):
170
+ """Domain payload for `PermissionRequest`."""
171
+
172
+ event: Literal[HookEvent.PERMISSION_REQUEST]
173
+ call: ToolCallData
174
+
175
+
176
+ class NotificationEvent(_DomainModel):
177
+ """Domain payload for `Notification`."""
178
+
179
+ event: Literal[HookEvent.NOTIFICATION]
180
+ notification: OpscloudNotification
181
+
182
+
183
+ class PreToolUseEvent(_DomainModel):
184
+ """Domain payload for `PreToolUse`."""
185
+
186
+ event: Literal[HookEvent.PRE_TOOL_USE]
187
+ call: ToolCallData
188
+
189
+
190
+ class PostToolUseEvent(_DomainModel):
191
+ """Domain payload for `PostToolUse`."""
192
+
193
+ event: Literal[HookEvent.POST_TOOL_USE]
194
+ call: ToolCallData
195
+ result: JsonValue
196
+ duration_ms: int | None = None
197
+
198
+ @classmethod
199
+ def from_tool_result(
200
+ cls,
201
+ result: ToolMessage | Command[Any],
202
+ *,
203
+ call: ToolCallData,
204
+ duration_ms: int | None = None,
205
+ ) -> PostToolUseEvent:
206
+ """Construct a PostToolUseEvent from a tool execution result.
207
+
208
+ Args:
209
+ result: Tool execution result message or command.
210
+ call: Associated tool call data.
211
+ duration_ms: Execution duration in milliseconds, if available.
212
+
213
+ Returns:
214
+ PostToolUseEvent: Constructed domain event model.
215
+ """
216
+ if isinstance(result, ToolMessage):
217
+ value: object = result.model_dump(mode="json")
218
+ else:
219
+ value = JSON_VALUE_ADAPTER.dump_python(cast(Any, result), mode="json", warnings=False)
220
+ return cls(
221
+ event=HookEvent.POST_TOOL_USE,
222
+ call=call,
223
+ result=JSON_VALUE_ADAPTER.validate_python(value),
224
+ duration_ms=duration_ms,
225
+ )
226
+
227
+
228
+ class PostToolUseFailureEvent(_DomainModel):
229
+ """Domain payload for `PostToolUseFailure`."""
230
+
231
+ event: Literal[HookEvent.POST_TOOL_USE_FAILURE]
232
+ call: ToolCallData
233
+ error: str
234
+ is_interrupt: bool = False
235
+ duration_ms: int | None = None
236
+
237
+
238
+ class PreCompactEvent(_DomainModel):
239
+ """Domain payload for `PreCompact`."""
240
+
241
+ event: Literal[HookEvent.PRE_COMPACT]
242
+ trigger: CompactTrigger
243
+ custom_instructions: str = ""
244
+
245
+
246
+ class StopEvent(_DomainModel):
247
+ """Domain payload for `Stop`."""
248
+
249
+ event: Literal[HookEvent.STOP]
250
+ continuation_count: int
251
+ last_assistant_message: str
252
+ background_tasks: list[BackgroundTaskSnapshot] = Field(default_factory=list)
253
+ session_crons: list[SessionCronSnapshot] = Field(default_factory=list)
254
+
255
+
256
+ class SubagentStartEvent(_DomainModel):
257
+ """Domain payload for `SubagentStart`."""
258
+
259
+ event: Literal[HookEvent.SUBAGENT_START]
260
+ agent: AgentIdentity
261
+
262
+
263
+ class SubagentStopEvent(_DomainModel):
264
+ """Domain payload for `SubagentStop`."""
265
+
266
+ event: Literal[HookEvent.SUBAGENT_STOP]
267
+ agent: AgentIdentity
268
+ continuation_count: int
269
+ last_assistant_message: str
270
+ transcript_revision: str | None = None
271
+ background_tasks: list[BackgroundTaskSnapshot] = Field(default_factory=list)
272
+ session_crons: list[SessionCronSnapshot] = Field(default_factory=list)
273
+
274
+
275
+ type HookDomainEvent = Annotated[
276
+ SessionStartEvent
277
+ | UserPromptSubmitEvent
278
+ | SessionEndEvent
279
+ | PermissionRequestEvent
280
+ | NotificationEvent
281
+ | PreToolUseEvent
282
+ | PostToolUseEvent
283
+ | PostToolUseFailureEvent
284
+ | PreCompactEvent
285
+ | StopEvent
286
+ | SubagentStartEvent
287
+ | SubagentStopEvent,
288
+ Field(discriminator="event"),
289
+ ]
290
+
291
+
292
+ class HookInvocation(_DomainModel):
293
+ """A domain hook event with its invocation context."""
294
+
295
+ context: HookContext
296
+ event: HookDomainEvent
297
+
298
+
299
+ class HookDiagnostic(_DomainModel):
300
+ """Structured diagnostic produced while processing a hook."""
301
+
302
+ code: str
303
+ severity: Literal["debug", "warning", "error"]
304
+ message: str
305
+ handler_id: str | None = None
306
+ field: str | None = None
307
+
308
+
309
+ class PermissionEffect(_DomainModel):
310
+ """Normalized permission result from hook processing."""
311
+
312
+ behavior: Literal["allow", "deny", "ask", "none"]
313
+ reason: str | None = None
314
+ interrupt: bool = False
315
+
316
+
317
+ class BaseHookDecision(_DomainModel):
318
+ """Fields common to every event-specific hook decision."""
319
+
320
+ continue_processing: bool = True
321
+ stop_reason: str | None = None
322
+ user_notices: list[str] = Field(default_factory=list)
323
+ terminal_sequences: list[str] = Field(default_factory=list)
324
+ diagnostics: list[HookDiagnostic] = Field(default_factory=list)
325
+
326
+
327
+ class SessionStartDecision(BaseHookDecision):
328
+ """Decision returned for `SessionStart`."""
329
+
330
+ event: Literal[HookEvent.SESSION_START]
331
+ context: list[str] = Field(default_factory=list)
332
+
333
+
334
+ class UserPromptSubmitDecision(BaseHookDecision):
335
+ """Decision returned for `UserPromptSubmit`."""
336
+
337
+ event: Literal[HookEvent.USER_PROMPT_SUBMIT]
338
+ context: list[str] = Field(default_factory=list)
339
+ suppress_original_prompt: bool = False
340
+
341
+
342
+ class SessionEndDecision(BaseHookDecision):
343
+ """Decision returned for `SessionEnd`."""
344
+
345
+ event: Literal[HookEvent.SESSION_END]
346
+
347
+
348
+ class PermissionRequestDecision(BaseHookDecision):
349
+ """Decision returned for `PermissionRequest`."""
350
+
351
+ event: Literal[HookEvent.PERMISSION_REQUEST]
352
+ permission: PermissionEffect
353
+
354
+
355
+ class NotificationDecision(BaseHookDecision):
356
+ """Decision returned for `Notification`."""
357
+
358
+ event: Literal[HookEvent.NOTIFICATION]
359
+
360
+
361
+ class PreToolUseDecision(BaseHookDecision):
362
+ """Decision returned for `PreToolUse`."""
363
+
364
+ event: Literal[HookEvent.PRE_TOOL_USE]
365
+ permission: PermissionEffect
366
+ context: list[str] = Field(default_factory=list)
367
+
368
+
369
+ class PostToolUseDecision(BaseHookDecision):
370
+ """Decision returned for `PostToolUse`."""
371
+
372
+ event: Literal[HookEvent.POST_TOOL_USE]
373
+ feedback: list[str] = Field(default_factory=list)
374
+ context: list[str] = Field(default_factory=list)
375
+
376
+
377
+ class PostToolUseFailureDecision(BaseHookDecision):
378
+ """Decision returned for `PostToolUseFailure`."""
379
+
380
+ event: Literal[HookEvent.POST_TOOL_USE_FAILURE]
381
+ feedback: list[str] = Field(default_factory=list)
382
+ context: list[str] = Field(default_factory=list)
383
+
384
+
385
+ class PreCompactDecision(BaseHookDecision):
386
+ """Decision returned for `PreCompact`."""
387
+
388
+ event: Literal[HookEvent.PRE_COMPACT]
389
+
390
+
391
+ class StopDecision(BaseHookDecision):
392
+ """Decision returned for `Stop`."""
393
+
394
+ event: Literal[HookEvent.STOP]
395
+ continue_loop: bool
396
+ feedback: list[str] = Field(default_factory=list)
397
+
398
+
399
+ class SubagentStartDecision(BaseHookDecision):
400
+ """Decision returned for `SubagentStart`."""
401
+
402
+ event: Literal[HookEvent.SUBAGENT_START]
403
+ context: list[str] = Field(default_factory=list)
404
+
405
+
406
+ class SubagentStopDecision(BaseHookDecision):
407
+ """Decision returned for `SubagentStop`."""
408
+
409
+ event: Literal[HookEvent.SUBAGENT_STOP]
410
+ context: list[str] = Field(default_factory=list)
411
+
412
+
413
+ type HookDecision = Annotated[
414
+ SessionStartDecision
415
+ | UserPromptSubmitDecision
416
+ | SessionEndDecision
417
+ | PermissionRequestDecision
418
+ | NotificationDecision
419
+ | PreToolUseDecision
420
+ | PostToolUseDecision
421
+ | PostToolUseFailureDecision
422
+ | PreCompactDecision
423
+ | StopDecision
424
+ | SubagentStartDecision
425
+ | SubagentStopDecision,
426
+ Field(discriminator="event"),
427
+ ]
428
+
429
+
430
+ class HookEffect(_DomainModel):
431
+ """Normalized effect produced by one hook handler."""
432
+
433
+ handler_id: str
434
+ decision: HookDecision
@@ -0,0 +1,37 @@
1
+ """Versioned hook invocation transport models."""
2
+
3
+ from __future__ import annotations
4
+
5
+ from datetime import datetime
6
+ from typing import Literal
7
+ from uuid import UUID
8
+
9
+ from pydantic import BaseModel, ConfigDict
10
+
11
+ from opscloud.hooks.models.domain import HookDecision, HookInvocation
12
+
13
+
14
+ class _TransportModel(BaseModel):
15
+ """Base model for hook transport payloads with wire-format helpers."""
16
+
17
+ model_config = ConfigDict(extra="forbid")
18
+
19
+
20
+ class HookInvocationRequest(_TransportModel):
21
+ """Request sent for a server-owned hook invocation."""
22
+
23
+ protocol_version: Literal[1]
24
+ invocation_id: UUID
25
+ snapshot_id: str
26
+ run_id: str
27
+ invocation: HookInvocation
28
+ deadline: datetime
29
+
30
+
31
+ class HookInvocationResponse(_TransportModel):
32
+ """Response returned for a server-owned hook invocation."""
33
+
34
+ protocol_version: Literal[1]
35
+ invocation_id: UUID
36
+ snapshot_id: str
37
+ decision: HookDecision
@@ -0,0 +1,231 @@
1
+ """Native OpsCloud tool vocabulary mapped to compatible wire names."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import re
6
+ from typing import TYPE_CHECKING
7
+
8
+ if TYPE_CHECKING:
9
+ from collections.abc import Callable
10
+
11
+ from opscloud.hooks.models.domain import ToolCallData
12
+ from opscloud.json_types import JsonObject
13
+
14
+
15
+ def _select(args: JsonObject, *fields: str) -> JsonObject:
16
+ """Filter dictionary to only contain specified keys if present.
17
+
18
+ Args:
19
+ args: Input argument dictionary.
20
+ *fields: Allowed field names to preserve.
21
+
22
+ Returns:
23
+ Filtered dictionary containing only the specified present keys.
24
+ """
25
+ return {field: args[field] for field in fields if field in args}
26
+
27
+
28
+ def _bash_input(args: JsonObject) -> JsonObject:
29
+ """Project execute/bash arguments to wire inputs, converting seconds to milliseconds.
30
+
31
+ Args:
32
+ args: Native tool argument dictionary.
33
+
34
+ Returns:
35
+ Wire input dictionary with timeout in milliseconds.
36
+ """
37
+ result = _select(args, "command")
38
+ if "timeout" in args:
39
+ timeout = args["timeout"]
40
+ result["timeout"] = timeout * 1000 if isinstance(timeout, int) and not isinstance(timeout, bool) else timeout
41
+ return result
42
+
43
+
44
+ def _write_input(args: JsonObject) -> JsonObject:
45
+ """Project write_file arguments to wire inputs.
46
+
47
+ Args:
48
+ args: Native tool argument dictionary.
49
+
50
+ Returns:
51
+ Wire input dictionary with file_path and content.
52
+ """
53
+ return _select(args, "file_path", "content")
54
+
55
+
56
+ def _edit_input(args: JsonObject) -> JsonObject:
57
+ """Project edit_file arguments to wire inputs.
58
+
59
+ Args:
60
+ args: Native tool argument dictionary.
61
+
62
+ Returns:
63
+ Wire input dictionary with replacement details.
64
+ """
65
+ return _select(args, "file_path", "old_string", "new_string", "replace_all")
66
+
67
+
68
+ def _read_input(args: JsonObject) -> JsonObject:
69
+ """Project read_file arguments to wire inputs, converting 0-based offset to 1-based.
70
+
71
+ Args:
72
+ args: Native tool argument dictionary.
73
+
74
+ Returns:
75
+ Wire input dictionary with 1-based offset.
76
+ """
77
+ result = _select(args, "file_path", "limit")
78
+ if "offset" in args:
79
+ offset = args["offset"]
80
+ result["offset"] = offset + 1 if isinstance(offset, int) and not isinstance(offset, bool) else offset
81
+ return result
82
+
83
+
84
+ def _glob_input(args: JsonObject) -> JsonObject:
85
+ """Project glob arguments to wire inputs.
86
+
87
+ Args:
88
+ args: Native tool argument dictionary.
89
+
90
+ Returns:
91
+ Wire input dictionary with pattern and path.
92
+ """
93
+ return _select(args, "pattern", "path")
94
+
95
+
96
+ def _grep_input(args: JsonObject) -> JsonObject:
97
+ """Project grep arguments to wire inputs, escaping regex and mapping head limit.
98
+
99
+ Args:
100
+ args: Native tool argument dictionary.
101
+
102
+ Returns:
103
+ Wire input dictionary for wire Grep tool.
104
+ """
105
+ result = _select(args, "path", "glob", "output_mode")
106
+ if "pattern" in args:
107
+ pattern = args["pattern"]
108
+ result["pattern"] = re.escape(pattern) if isinstance(pattern, str) else pattern
109
+ if "max_count" in args:
110
+ result["head_limit"] = args["max_count"]
111
+ return result
112
+
113
+
114
+ def _ls_input(args: JsonObject) -> JsonObject:
115
+ """Project ls arguments to wire inputs.
116
+
117
+ Args:
118
+ args: Native tool argument dictionary.
119
+
120
+ Returns:
121
+ Wire input dictionary with path.
122
+ """
123
+ return _select(args, "path")
124
+
125
+
126
+ def _web_search_input(args: JsonObject) -> JsonObject:
127
+ """Project web_search arguments to wire inputs.
128
+
129
+ Args:
130
+ args: Native tool argument dictionary.
131
+
132
+ Returns:
133
+ Wire input dictionary with query and max_results.
134
+ """
135
+ return _select(args, "query", "max_results")
136
+
137
+
138
+ def _fetch_url_input(args: JsonObject) -> JsonObject:
139
+ """Project fetch_url arguments to wire inputs.
140
+
141
+ Args:
142
+ args: Native tool argument dictionary.
143
+
144
+ Returns:
145
+ Wire input dictionary with url and timeout.
146
+ """
147
+ return _select(args, "url", "timeout")
148
+
149
+
150
+ _NATIVE_TO_WIRE: dict[str, tuple[str, Callable[[JsonObject], JsonObject]]] = {
151
+ "execute": ("Bash", _bash_input),
152
+ "write_file": ("Write", _write_input),
153
+ "edit_file": ("Edit", _edit_input),
154
+ "read_file": ("Read", _read_input),
155
+ "glob": ("Glob", _glob_input),
156
+ "grep": ("Grep", _grep_input),
157
+ "ls": ("LS", _ls_input),
158
+ "web_search": ("WebSearch", _web_search_input),
159
+ "fetch_url": ("WebFetch", _fetch_url_input),
160
+ "fetch_web_page": ("WebFetch", _fetch_url_input),
161
+ }
162
+
163
+ _MCP_WIRE_RE = re.compile(r"^mcp__.+__.+$")
164
+
165
+
166
+ def format_mcp_wire_name(server: str, tool: str) -> str:
167
+ """Format a compatible MCP wire tool name.
168
+
169
+ Args:
170
+ server: MCP server identifier.
171
+ tool: Tool name on the MCP server.
172
+
173
+ Returns:
174
+ Standardized wire representation `mcp__{server}__{tool}`.
175
+ """
176
+ return f"mcp__{server}__{tool}"
177
+
178
+
179
+ def to_wire_tool_name(
180
+ name: str,
181
+ *,
182
+ mcp_server: str | None = None,
183
+ ) -> str:
184
+ """Map a native tool name to the compatible wire tool name.
185
+
186
+ Args:
187
+ name: Native tool name or MCP tool name.
188
+ mcp_server: Optional MCP server name if this tool belongs to an MCP server.
189
+
190
+ Returns:
191
+ Standardized wire name (e.g. 'Bash', 'mcp__server__tool', or original name).
192
+ """
193
+ if _MCP_WIRE_RE.fullmatch(name) is not None:
194
+ return name
195
+ if mcp_server is not None:
196
+ prefix = f"{mcp_server}_"
197
+ tool = name.removeprefix(prefix) if name.startswith(prefix) else name
198
+ return format_mcp_wire_name(mcp_server, tool)
199
+ adapter = _NATIVE_TO_WIRE.get(name)
200
+ return adapter[0] if adapter is not None else name
201
+
202
+
203
+ def to_wire_tool_input(name: str, args: JsonObject) -> JsonObject:
204
+ """Map native tool arguments to the compatible wire input object.
205
+
206
+ Args:
207
+ name: Native tool name.
208
+ args: Input argument dictionary.
209
+
210
+ Returns:
211
+ Adapted wire input dictionary.
212
+ """
213
+ adapter = _NATIVE_TO_WIRE.get(name)
214
+ return adapter[1](args) if adapter is not None else dict(args)
215
+
216
+
217
+ def to_wire_call(
218
+ call: ToolCallData,
219
+ ) -> tuple[str, JsonObject]:
220
+ """Project a native tool call into compatible wire name and input.
221
+
222
+ Args:
223
+ call: Native ToolCallData instance.
224
+
225
+ Returns:
226
+ A tuple of (wire_tool_name, wire_tool_input).
227
+ """
228
+ name = to_wire_tool_name(call.name, mcp_server=call.mcp_server)
229
+ if call.mcp_server is not None or _MCP_WIRE_RE.fullmatch(call.name) is not None:
230
+ return name, dict(call.args)
231
+ return name, to_wire_tool_input(call.name, call.args)