agentengine-sdk-python 0.7.0__py3-none-any.whl → 0.8.1__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 (450) hide show
  1. {agentengine_sdk_python-0.7.0.dist-info → agentengine_sdk_python-0.8.1.dist-info}/METADATA +52 -20
  2. agentengine_sdk_python-0.8.1.dist-info/RECORD +644 -0
  3. {agentengine_sdk_python-0.7.0.dist-info → agentengine_sdk_python-0.8.1.dist-info}/WHEEL +1 -1
  4. ksadk/a2a/__init__.py +180 -11
  5. ksadk/a2a/bootstrap.py +332 -0
  6. ksadk/a2a/card.py +15 -0
  7. ksadk/a2a/context_store.py +203 -0
  8. ksadk/a2a/control_plane.py +1056 -0
  9. ksadk/a2a/credential.py +99 -0
  10. ksadk/a2a/event_adapter.py +149 -0
  11. ksadk/a2a/executor.py +361 -137
  12. ksadk/a2a/external_transport.py +516 -0
  13. ksadk/a2a/identity.py +304 -0
  14. ksadk/a2a/ids.py +22 -0
  15. ksadk/a2a/langgraph.py +285 -0
  16. ksadk/a2a/resume_store.py +201 -0
  17. ksadk/a2a/routes.py +112 -0
  18. ksadk/a2a/server.py +102 -62
  19. ksadk/a2a/service_env.py +33 -0
  20. ksadk/a2a/space_client.py +1122 -0
  21. ksadk/a2a/task_adapter.py +423 -0
  22. ksadk/a2a/task_event_dispatcher.py +167 -0
  23. ksadk/a2a/task_event_outbox.py +326 -0
  24. ksadk/a2a/task_store.py +206 -0
  25. ksadk/a2a_card.py +101 -0
  26. ksadk/a2ui/__init__.py +27 -0
  27. ksadk/a2ui/core.py +186 -0
  28. ksadk/a2ui/models.py +166 -0
  29. ksadk/a2ui/renderer.py +198 -0
  30. ksadk/agui/__init__.py +9 -0
  31. ksadk/agui/a2ui_projection.py +92 -0
  32. ksadk/agui/agent.py +872 -0
  33. ksadk/agui/config.py +92 -0
  34. ksadk/agui/routes.py +47 -0
  35. ksadk/api/client.py +238 -204
  36. ksadk/api/environment.py +27 -0
  37. ksadk/builders/__init__.py +2 -0
  38. ksadk/builders/base.py +16 -14
  39. ksadk/builders/code_builder.py +375 -270
  40. ksadk/builders/container_builder.py +240 -200
  41. ksadk/builders/framework_requirements.py +31 -12
  42. ksadk/builders/ks3_uploader.py +60 -29
  43. ksadk/builders/managed_runtime_builder.py +173 -0
  44. ksadk/builders/mcp_builder.py +91 -92
  45. ksadk/builders/requirements_utils.py +1 -5
  46. ksadk/cli/__init__.py +97 -171
  47. ksadk/cli/cmd_a2a.py +255 -84
  48. ksadk/cli/cmd_agent.py +19 -5
  49. ksadk/cli/cmd_build.py +158 -29
  50. ksadk/cli/cmd_completion.py +47 -35
  51. ksadk/cli/cmd_config.py +267 -198
  52. ksadk/cli/cmd_create.py +507 -740
  53. ksadk/cli/cmd_dashboard.py +120 -45
  54. ksadk/cli/cmd_deploy.py +135 -59
  55. ksadk/cli/cmd_destroy.py +44 -14
  56. ksadk/cli/cmd_eval.py +386 -0
  57. ksadk/cli/cmd_files.py +63 -24
  58. ksadk/cli/cmd_hermes.py +313 -135
  59. ksadk/cli/cmd_invoke.py +184 -122
  60. ksadk/cli/cmd_launch.py +76 -28
  61. ksadk/cli/cmd_mcp.py +98 -64
  62. ksadk/cli/cmd_model.py +14 -5
  63. ksadk/cli/cmd_openclaw.py +564 -268
  64. ksadk/cli/cmd_replay.py +71 -0
  65. ksadk/cli/cmd_run.py +58 -73
  66. ksadk/cli/cmd_status.py +80 -31
  67. ksadk/cli/cmd_studio.py +110 -0
  68. ksadk/cli/cmd_version.py +20 -13
  69. ksadk/cli/cmd_web.py +95 -18
  70. ksadk/cli/deploy_utils.py +20 -20
  71. ksadk/cli/dry_run.py +7 -4
  72. ksadk/cli/env_options.py +83 -0
  73. ksadk/cli/error_utils.py +37 -12
  74. ksadk/cli/global_options.py +4 -3
  75. ksadk/cli/local_runtime.py +1 -2
  76. ksadk/cli/model_catalog.py +6 -2
  77. ksadk/cli/network_options.py +41 -19
  78. ksadk/cli/resource_common.py +6 -2
  79. ksadk/cli/runtime_bootstrap.py +51 -0
  80. ksadk/cli/storage.py +0 -1
  81. ksadk/cli/ui.py +11 -3
  82. ksadk/cli/workflow_common.py +52 -18
  83. ksadk/codex/__init__.py +12 -0
  84. ksadk/codex/client.py +1042 -0
  85. ksadk/codex/phase.py +143 -0
  86. ksadk/codex/runtime.py +940 -0
  87. ksadk/common/aicp_env.py +0 -1
  88. ksadk/common/auth.py +2 -2
  89. ksadk/common/constants.py +1 -3
  90. ksadk/common/kop_client.py +232 -0
  91. ksadk/common/llm_utils.py +17 -13
  92. ksadk/compat/__init__.py +5 -0
  93. ksadk/compat/adk_compat.py +200 -0
  94. ksadk/compat/copilotkit_a2ui.py +330 -0
  95. ksadk/configs/__init__.py +12 -14
  96. ksadk/configs/env_registry.py +661 -116
  97. ksadk/configs/global_config.py +3 -2
  98. ksadk/configs/settings.py +133 -209
  99. ksadk/conversations/__init__.py +85 -92
  100. ksadk/conversations/attachment_storage.py +16 -11
  101. ksadk/conversations/attachments.py +44 -36
  102. ksadk/conversations/compaction_pipeline.py +12 -12
  103. ksadk/conversations/compaction_prompt.py +9 -5
  104. ksadk/conversations/context.py +221 -6
  105. ksadk/conversations/message_projection.py +438 -51
  106. ksadk/conversations/model_context.py +12 -6
  107. ksadk/conversations/model_options.py +0 -1
  108. ksadk/conversations/normalize.py +20 -16
  109. ksadk/conversations/reasoning_markup.py +1 -1
  110. ksadk/conversations/runtime.py +339 -5255
  111. ksadk/conversations/runtime_compaction.py +333 -0
  112. ksadk/conversations/runtime_constants.py +27 -0
  113. ksadk/conversations/runtime_governance.py +185 -0
  114. ksadk/conversations/runtime_input.py +660 -0
  115. ksadk/conversations/runtime_invocation.py +395 -0
  116. ksadk/conversations/runtime_metadata.py +475 -0
  117. ksadk/conversations/runtime_observability.py +367 -0
  118. ksadk/conversations/runtime_payloads.py +272 -0
  119. ksadk/conversations/runtime_persistence.py +440 -0
  120. ksadk/conversations/runtime_preparation.py +426 -0
  121. ksadk/conversations/runtime_resume.py +836 -0
  122. ksadk/conversations/runtime_stream_events.py +902 -0
  123. ksadk/conversations/runtime_streaming.py +700 -0
  124. ksadk/conversations/semantic_summary.py +17 -5
  125. ksadk/conversations/session_title.py +6 -3
  126. ksadk/deployment/__init__.py +15 -16
  127. ksadk/deployment/agent_access.py +12 -23
  128. ksadk/deployment/base.py +51 -38
  129. ksadk/deployment/managed_runtime.py +33 -0
  130. ksadk/deployment/manager.py +85 -71
  131. ksadk/deployment/providers/serverless.py +379 -210
  132. ksadk/deployment/registry.py +38 -32
  133. ksadk/deployment/state.py +11 -11
  134. ksadk/deployment/ui_config.py +1 -1
  135. ksadk/detection/__init__.py +1 -1
  136. ksadk/detection/detector.py +146 -83
  137. ksadk/detection/mcp_detector.py +9 -6
  138. ksadk/evaluation/__init__.py +84 -0
  139. ksadk/evaluation/a2a_adapter.py +444 -0
  140. ksadk/evaluation/adapters.py +54 -0
  141. ksadk/evaluation/contracts.py +409 -0
  142. ksadk/evaluation/evalset.py +351 -0
  143. ksadk/evaluation/evaluators.py +461 -0
  144. ksadk/evaluation/executor.py +118 -0
  145. ksadk/evaluation/storage.py +68 -0
  146. ksadk/evaluation/target.py +73 -0
  147. ksadk/events/__init__.py +25 -0
  148. ksadk/events/parser.py +191 -0
  149. ksadk/events/replay.py +37 -0
  150. ksadk/events/runtime_event.py +273 -0
  151. ksadk/events/store.py +317 -0
  152. ksadk/harness/__init__.py +35 -0
  153. ksadk/harness/app.py +269 -0
  154. ksadk/harness/config.py +181 -0
  155. ksadk/harness/reasoner.py +105 -0
  156. ksadk/harness/runtime.py +364 -0
  157. ksadk/harness/sandbox.py +141 -0
  158. ksadk/harness/tools.py +222 -0
  159. ksadk/hermes_terminal.py +28 -12
  160. ksadk/identity/resolver.py +15 -9
  161. ksadk/ids.py +32 -0
  162. ksadk/knowledge_base/adk_tool.py +1 -1
  163. ksadk/knowledge_base/client.py +38 -33
  164. ksadk/managed_a2a_card.py +160 -0
  165. ksadk/managed_runtime.py +195 -0
  166. ksadk/markdown.py +5 -2
  167. ksadk/mcp_runtime/__init__.py +9 -6
  168. ksadk/memory/__init__.py +1 -1
  169. ksadk/memory/adk/__init__.py +2 -0
  170. ksadk/memory/adk/backends/base_ltm_backend.py +2 -6
  171. ksadk/memory/adk/backends/http_ltm_backend.py +13 -21
  172. ksadk/memory/adk/backends/inmemory_ltm_backend.py +7 -13
  173. ksadk/memory/adk/backends/sdk_ltm_backend.py +36 -36
  174. ksadk/memory/adk/long_term_memory.py +34 -37
  175. ksadk/memory/adk/resilient_session_service.py +4 -5
  176. ksadk/memory/adk/short_term_memory.py +12 -21
  177. ksadk/memory/adk_tool.py +3 -2
  178. ksadk/memory/backends/base.py +19 -19
  179. ksadk/memory/backends/memory.py +24 -25
  180. ksadk/memory/backends/redis.py +31 -30
  181. ksadk/memory/langchain_tool.py +2 -1
  182. ksadk/memory/manager.py +52 -47
  183. ksadk/memory/service.py +16 -6
  184. ksadk/memory/tool.py +4 -0
  185. ksadk/model_policy.py +15 -7
  186. ksadk/model_proxy/__init__.py +51 -0
  187. ksadk/model_proxy/bootstrap.py +80 -0
  188. ksadk/model_proxy/cache.py +165 -0
  189. ksadk/model_proxy/config.py +66 -0
  190. ksadk/model_proxy/demo_webui.py +115 -0
  191. ksadk/model_proxy/detect.py +145 -0
  192. ksadk/model_proxy/gate.py +68 -0
  193. ksadk/model_proxy/namespace.py +201 -0
  194. ksadk/model_proxy/protocol_proxy.py +22 -0
  195. ksadk/model_proxy/server.py +443 -0
  196. ksadk/model_proxy/transform.py +735 -0
  197. ksadk/openclaw_gateway.py +29 -14
  198. ksadk/runners/adk_runner.py +354 -146
  199. ksadk/runners/base_runner.py +71 -29
  200. ksadk/runners/deepagents_runner.py +0 -1
  201. ksadk/runners/factory.py +18 -5
  202. ksadk/runners/langchain_runner.py +29 -742
  203. ksadk/runners/langgraph_runner.py +417 -97
  204. ksadk/runners/patch_langchain.py +16 -16
  205. ksadk/runners/remote_runner.py +134 -33
  206. ksadk/runners/usage_accumulator.py +1 -0
  207. ksadk/runners/utils/__init__.py +0 -10
  208. ksadk/runners/utils/loader.py +23 -7
  209. ksadk/runtime/__init__.py +67 -0
  210. ksadk/runtime/adapter.py +412 -0
  211. ksadk/runtime/conversation_execution.py +553 -0
  212. ksadk/runtime/executor.py +251 -0
  213. ksadk/runtime/factory.py +156 -0
  214. ksadk/runtime/framework_adapters.py +118 -0
  215. ksadk/runtime/launch.py +48 -0
  216. ksadk/runtime/preprocessing.py +131 -0
  217. ksadk/runtime/runner_adapter.py +1032 -0
  218. ksadk/runtime/runner_loading.py +36 -0
  219. ksadk/runtime_context.py +18 -3
  220. ksadk/runtime_state.py +0 -1
  221. ksadk/sandbox/__init__.py +4 -1
  222. ksadk/sandbox/backends/__init__.py +4 -1
  223. ksadk/sandbox/backends/e2b.py +13 -5
  224. ksadk/sandbox/backends/local_process.py +11 -3
  225. ksadk/sandbox/base.py +10 -15
  226. ksadk/sandbox/factory.py +14 -4
  227. ksadk/sandbox/registry.py +57 -6
  228. ksadk/server/__init__.py +39 -4
  229. ksadk/server/api_models.py +15 -5
  230. ksadk/server/app.py +24 -3928
  231. ksadk/server/composition.py +47 -0
  232. ksadk/server/factory.py +622 -0
  233. ksadk/server/routes/__init__.py +1 -0
  234. ksadk/server/routes/checkpoint_resolution.py +116 -0
  235. ksadk/server/routes/common.py +682 -0
  236. ksadk/server/routes/control.py +331 -0
  237. ksadk/server/routes/dependencies.py +98 -0
  238. ksadk/server/routes/misc.py +425 -0
  239. ksadk/server/routes/models.py +451 -0
  240. ksadk/server/routes/openai_compat.py +229 -0
  241. ksadk/server/routes/projection.py +848 -0
  242. ksadk/server/routes/routers.py +52 -0
  243. ksadk/server/routes/run.py +519 -0
  244. ksadk/server/routes/sessions.py +644 -0
  245. ksadk/server/routes/streaming.py +265 -0
  246. ksadk/server/routes/workspace.py +414 -0
  247. ksadk/server/static/assets/{ArtifactsPanel-D-SSn2ee.js → ArtifactsPanel-CakCqxEN.js} +1 -1
  248. ksadk/server/static/assets/CodeBlock-CynLknyO.js +9 -0
  249. ksadk/server/static/assets/MathMessageMarkdown-3sQdOysS.js +8 -0
  250. ksadk/server/static/assets/MermaidBlock-NERD_ef7.js +303 -0
  251. ksadk/server/static/assets/NativeTerminalPanel-CiHWf82q.js +1 -0
  252. ksadk/server/static/assets/{arc-BA13sHc9.js → arc-DrgjcKhl.js} +1 -1
  253. ksadk/server/static/assets/architecture-7EHR7CIX-CpZLRCcY.js +1 -0
  254. ksadk/server/static/assets/{architectureDiagram-3BPJPVTR-DzJzgVoL.js → architectureDiagram-3BPJPVTR-BXoVRbQ6.js} +1 -1
  255. ksadk/server/static/assets/{blockDiagram-GPEHLZMM-UTdVcZhn.js → blockDiagram-GPEHLZMM-BnaB3Ywv.js} +1 -1
  256. ksadk/server/static/assets/{c4Diagram-AAUBKEIU-Dix0GD4m.js → c4Diagram-AAUBKEIU-Dw4weZcp.js} +1 -1
  257. ksadk/server/static/assets/channel-Dt3rQTFI.js +1 -0
  258. ksadk/server/static/assets/{chunk-2J33WTMH-C2JxuZ42.js → chunk-2J33WTMH-ChjpLK7j.js} +1 -1
  259. ksadk/server/static/assets/{chunk-4BX2VUAB-Be57QPgD.js → chunk-4BX2VUAB-B9drTgOW.js} +1 -1
  260. ksadk/server/static/assets/{chunk-55IACEB6-WjSuy4nv.js → chunk-55IACEB6-CK4ROATy.js} +1 -1
  261. ksadk/server/static/assets/{chunk-727SXJPM-BOovP-b5.js → chunk-727SXJPM-B9KtTTgw.js} +1 -1
  262. ksadk/server/static/assets/{chunk-AQP2D5EJ-DOmZNmWj.js → chunk-AQP2D5EJ-1O1mki3m.js} +1 -1
  263. ksadk/server/static/assets/{chunk-FMBD7UC4-DzwlodkU.js → chunk-FMBD7UC4-B_fH2YuH.js} +1 -1
  264. ksadk/server/static/assets/{chunk-ND2GUHAM-DMqAikEU.js → chunk-ND2GUHAM-D6rFLaVV.js} +1 -1
  265. ksadk/server/static/assets/chunk-QZHKN3VN-iXEZtKQc.js +1 -0
  266. ksadk/server/static/assets/classDiagram-4FO5ZUOK-DIveV17Q.js +1 -0
  267. ksadk/server/static/assets/classDiagram-v2-Q7XG4LA2-DIveV17Q.js +1 -0
  268. ksadk/server/static/assets/{cose-bilkent-S5V4N54A-Zhy2GBnP.js → cose-bilkent-S5V4N54A-ChNs_Mdk.js} +1 -1
  269. ksadk/server/static/assets/{dagre-BM42HDAG-CbKrtIUz.js → dagre-BM42HDAG-D0QXg_MQ.js} +1 -1
  270. ksadk/server/static/assets/{diagram-2AECGRRQ-BRApgQRK.js → diagram-2AECGRRQ-DBDDKwBQ.js} +1 -1
  271. ksadk/server/static/assets/{diagram-5GNKFQAL-D0xbnDiK.js → diagram-5GNKFQAL-BkwDOxmO.js} +1 -1
  272. ksadk/server/static/assets/{diagram-KO2AKTUF-CVugVI9L.js → diagram-KO2AKTUF-Bv8waYvY.js} +1 -1
  273. ksadk/server/static/assets/{diagram-LMA3HP47-DozUGgee.js → diagram-LMA3HP47-e1VECDdu.js} +1 -1
  274. ksadk/server/static/assets/{diagram-OG6HWLK6-ZOYsKlru.js → diagram-OG6HWLK6-Ds9adfRl.js} +1 -1
  275. ksadk/server/static/assets/{dist-DpKtt4Bo.js → dist-4N2NMVYg.js} +1 -1
  276. ksadk/server/static/assets/{dist-CkEKJFtk.js → dist-B-jNR6Vn.js} +1 -1
  277. ksadk/server/static/assets/{dist-D57wnGWd.js → dist-B5J2uhNk.js} +1 -1
  278. ksadk/server/static/assets/{dist-8_SfK1IP.js → dist-B5oS1zcj.js} +1 -1
  279. ksadk/server/static/assets/{dist-DMezvBGJ.js → dist-BB3-OwTQ.js} +1 -1
  280. ksadk/server/static/assets/{dist-2hInLS_J.js → dist-BIlKoW0k.js} +1 -1
  281. ksadk/server/static/assets/{dist-BrCcQ47T.js → dist-BjOdlDjj.js} +1 -1
  282. ksadk/server/static/assets/{dist-BmlMPsCc.js → dist-C1sz5Eo3.js} +1 -1
  283. ksadk/server/static/assets/{dist-B0NP_Z0z.js → dist-CWV4lDr1.js} +1 -1
  284. ksadk/server/static/assets/{dist-D-xOD048.js → dist-CmZHzlwZ.js} +1 -1
  285. ksadk/server/static/assets/{dist-DL_NKc_z.js → dist-D6MpCZtz.js} +1 -1
  286. ksadk/server/static/assets/{dist-DyOkZmze.js → dist-DJN_6Y39.js} +1 -1
  287. ksadk/server/static/assets/{dist-DmFaq_Iy.js → dist-DQU9EWw-.js} +1 -1
  288. ksadk/server/static/assets/{dist-gX6GOLKq.js → dist-DWKByxWV.js} +1 -1
  289. ksadk/server/static/assets/{dist-DyWsb78Q.js → dist-Dli7qW-B.js} +1 -1
  290. ksadk/server/static/assets/{dist-BIJVDMuB.js → dist-DsHPdk3W.js} +1 -1
  291. ksadk/server/static/assets/{dist-Dp0k7bWI.js → dist-X4TnqwOK.js} +1 -1
  292. ksadk/server/static/assets/{dist-8EEyGgDx.js → dist-_pHPTyZ-.js} +1 -1
  293. ksadk/server/static/assets/{dist-CPBtqRTW.js → dist-fhOuWds5.js} +1 -1
  294. ksadk/server/static/assets/{dist-D-JMdWPQ.js → dist-gLnrGsoU.js} +1 -1
  295. ksadk/server/static/assets/{dist-BssVmjIo.js → dist-j6Dxmf_j.js} +1 -1
  296. ksadk/server/static/assets/{dist-C3HIIaN5.js → dist-o2OVmKvt.js} +1 -1
  297. ksadk/server/static/assets/{erDiagram-TEJ5UH35-Bk-9bgE5.js → erDiagram-TEJ5UH35-BPItFKH6.js} +1 -1
  298. ksadk/server/static/assets/eventmodeling-FCH6USID-DYFSxbqr.js +1 -0
  299. ksadk/server/static/assets/{flowDiagram-I6XJVG4X-Dn9kZVuZ.js → flowDiagram-I6XJVG4X-BbYB9w5Y.js} +1 -1
  300. ksadk/server/static/assets/{ganttDiagram-6RSMTGT7-BGxXlJqm.js → ganttDiagram-6RSMTGT7-TQXa0KXv.js} +1 -1
  301. ksadk/server/static/assets/gitGraph-WXDBUCRP-DyNYp6BN.js +1 -0
  302. ksadk/server/static/assets/{gitGraphDiagram-PVQCEYII-C7Q0X-wi.js → gitGraphDiagram-PVQCEYII-bKblCnpa.js} +1 -1
  303. ksadk/server/static/assets/index-R52pJJvg.js +177 -0
  304. ksadk/server/static/assets/index-jJr3_955.css +2 -0
  305. ksadk/server/static/assets/info-J43DQDTF-WUx7qTde.js +1 -0
  306. ksadk/server/static/assets/{infoDiagram-5YYISTIA-BO_CSqq5.js → infoDiagram-5YYISTIA-BGVT7J_i.js} +1 -1
  307. ksadk/server/static/assets/{ishikawaDiagram-YF4QCWOH-eYLPLd46.js → ishikawaDiagram-YF4QCWOH-K0OOfVna.js} +1 -1
  308. ksadk/server/static/assets/{journeyDiagram-JHISSGLW-De9geSb0.js → journeyDiagram-JHISSGLW-8LeOJaZp.js} +1 -1
  309. ksadk/server/static/assets/{kanban-definition-UN3LZRKU-Cs80kQto.js → kanban-definition-UN3LZRKU-C6uCgZrW.js} +1 -1
  310. ksadk/server/static/assets/{katex-DSrCFD8n.js → katex-CYWseY5E.js} +1 -1
  311. ksadk/server/static/assets/{linear-CN9sbKTF.js → linear-hdBcYzM8.js} +1 -1
  312. ksadk/server/static/assets/{mermaid-parser.core-DlgSBU8l.js → mermaid-parser.core-BWrDjSZM.js} +2 -2
  313. ksadk/server/static/assets/{mindmap-definition-RKZ34NQL-9afz7Oug.js → mindmap-definition-RKZ34NQL-Bjy_2v4_.js} +1 -1
  314. ksadk/server/static/assets/packet-YPE3B663-BN13y_xl.js +1 -0
  315. ksadk/server/static/assets/pie-LRSECV5Y-ftSLXhhc.js +1 -0
  316. ksadk/server/static/assets/{pieDiagram-4H26LBE5-DPv_VstN.js → pieDiagram-4H26LBE5-GmmqNiVH.js} +1 -1
  317. ksadk/server/static/assets/{quadrantDiagram-W4KKPZXB-o77wZ1XK.js → quadrantDiagram-W4KKPZXB-BmkRbwCg.js} +1 -1
  318. ksadk/server/static/assets/radar-GUYGQ44K-jaICkIeO.js +1 -0
  319. ksadk/server/static/assets/{requirementDiagram-4Y6WPE33-BYVw81VC.js → requirementDiagram-4Y6WPE33-DSWFqL7c.js} +1 -1
  320. ksadk/server/static/assets/{sankeyDiagram-5OEKKPKP-B7nZFMKT.js → sankeyDiagram-5OEKKPKP-l6iXmU65.js} +1 -1
  321. ksadk/server/static/assets/{sequenceDiagram-3UESZ5HK-BGRRrFw5.js → sequenceDiagram-3UESZ5HK-Cq6UBeQB.js} +1 -1
  322. ksadk/server/static/assets/{stateDiagram-AJRCARHV-BUfHCoPs.js → stateDiagram-AJRCARHV-qzTQpg3Y.js} +1 -1
  323. ksadk/server/static/assets/stateDiagram-v2-BHNVJYJU-BYCoYGAN.js +1 -0
  324. ksadk/server/static/assets/{timeline-definition-PNZ67QCA-FbCTGrf9.js → timeline-definition-PNZ67QCA-DEz24vV0.js} +1 -1
  325. ksadk/server/static/assets/treeView-BLDUP644-Cpib_vlz.js +1 -0
  326. ksadk/server/static/assets/treemap-LRROVOQU-DQxfmVHK.js +1 -0
  327. ksadk/server/static/assets/{vennDiagram-CIIHVFJN-DWgwtPsJ.js → vennDiagram-CIIHVFJN-CMCixki2.js} +1 -1
  328. ksadk/server/static/assets/wardley-L42UT6IY-BQYHnnkU.js +1 -0
  329. ksadk/server/static/assets/{wardleyDiagram-YWT4CUSO-2x8G-tTM.js → wardleyDiagram-YWT4CUSO-CVzB8F9K.js} +1 -1
  330. ksadk/server/static/assets/{xychartDiagram-2RQKCTM6-Drma3AYl.js → xychartDiagram-2RQKCTM6-BFBqBLc1.js} +1 -1
  331. ksadk/server/static/index.html +2 -2
  332. ksadk/server/terminal_sessions.py +111 -58
  333. ksadk/sessions/__init__.py +69 -19
  334. ksadk/sessions/base.py +31 -11
  335. ksadk/sessions/continuity.py +2 -3
  336. ksadk/sessions/in_memory.py +46 -2
  337. ksadk/sessions/local_service.py +148 -17
  338. ksadk/sessions/postgres_service.py +143 -25
  339. ksadk/sessions/resilient.py +36 -8
  340. ksadk/skills/models.py +17 -5
  341. ksadk/skills/package_store.py +5 -2
  342. ksadk/skills/runtime/agent.py +20 -5
  343. ksadk/skills/runtime/artifacts.py +1 -5
  344. ksadk/skills/runtime/backends/e2b.py +10 -4
  345. ksadk/skills/runtime/backends/local.py +15 -3
  346. ksadk/skills/runtime/base.py +1 -2
  347. ksadk/skills/runtime/executor.py +10 -3
  348. ksadk/skills/runtime/factory.py +4 -2
  349. ksadk/skills/runtime/loader.py +1 -2
  350. ksadk/skills/runtime/registry.py +15 -10
  351. ksadk/skills/runtime/request.py +3 -1
  352. ksadk/skills/service_client.py +47 -16
  353. ksadk/skills/tool_defs.py +15 -10
  354. ksadk/studio/__init__.py +5 -0
  355. ksadk/studio/agent_avatar_assets.py +120 -0
  356. ksadk/studio/agent_lifecycle.py +51 -0
  357. ksadk/studio/api.py +1046 -0
  358. ksadk/studio/api_catalog_routes.py +324 -0
  359. ksadk/studio/api_contracts.py +177 -0
  360. ksadk/studio/api_helpers.py +132 -0
  361. ksadk/studio/authoring.py +524 -0
  362. ksadk/studio/authoring_coordinator.py +285 -0
  363. ksadk/studio/builder.py +320 -0
  364. ksadk/studio/capabilities.py +351 -0
  365. ksadk/studio/cloud.py +278 -0
  366. ksadk/studio/codex_agent_service.py +583 -0
  367. ksadk/studio/codex_builder.py +324 -0
  368. ksadk/studio/codex_manifest.py +278 -0
  369. ksadk/studio/codex_run.py +352 -0
  370. ksadk/studio/compiler.py +189 -0
  371. ksadk/studio/contracts.py +644 -0
  372. ksadk/studio/errors.py +47 -0
  373. ksadk/studio/evaluation.py +192 -0
  374. ksadk/studio/event_store.py +284 -0
  375. ksadk/studio/framework_run.py +114 -0
  376. ksadk/studio/identifiers.py +33 -0
  377. ksadk/studio/mcp_runtime.py +229 -0
  378. ksadk/studio/model_client.py +543 -0
  379. ksadk/studio/model_profile_service.py +214 -0
  380. ksadk/studio/operations.py +243 -0
  381. ksadk/studio/otel_trace.py +754 -0
  382. ksadk/studio/pagination.py +182 -0
  383. ksadk/studio/python_tool_inspection.py +183 -0
  384. ksadk/studio/repository.py +306 -0
  385. ksadk/studio/resource_catalog.py +1217 -0
  386. ksadk/studio/run_service.py +707 -0
  387. ksadk/studio/runtime_catalog.py +74 -0
  388. ksadk/studio/runtime_source.py +339 -0
  389. ksadk/studio/service.py +1141 -0
  390. ksadk/studio/shared_web.py +994 -0
  391. ksadk/studio/skill_discovery.py +628 -0
  392. ksadk/studio/static/assets/PrismRenderer-IYN-ffww.js +3 -0
  393. ksadk/studio/static/assets/index-CaEN0eTR.css +1 -0
  394. ksadk/studio/static/assets/index-DI2eY_NH.js +252 -0
  395. ksadk/studio/static/assets/react-vendor-BNmTiJ-I.js +9 -0
  396. ksadk/studio/static/assets/rolldown-runtime-hePW80VL.js +1 -0
  397. ksadk/studio/static/index.html +15 -0
  398. ksadk/studio/templates.py +630 -0
  399. ksadk/studio/validator.py +246 -0
  400. ksadk/studio/workspace.py +137 -0
  401. ksadk/terminal_exec_policy.py +3 -4
  402. ksadk/tools/gateway.py +101 -15
  403. ksadk/tools/result_budget.py +12 -4
  404. ksadk/toolsets/__init__.py +161 -37
  405. ksadk/toolsets/a2a.py +426 -0
  406. ksadk/toolsets/platform.py +21 -5
  407. ksadk/toolsets/sandbox.py +82 -16
  408. ksadk/toolsets/skills.py +200 -39
  409. ksadk/toolsets/web.py +123 -26
  410. ksadk/toolsets/workspace.py +212 -101
  411. ksadk/tracing/__init__.py +19 -21
  412. ksadk/tracing/exporters/inmemory_exporter.py +62 -51
  413. ksadk/tracing/setup.py +135 -506
  414. ksadk/tracing/span_utils.py +0 -41
  415. ksadk/tui/loop.py +78 -30
  416. ksadk/tui/stream_render.py +1 -0
  417. ksadk/ui_config.py +5 -3
  418. ksadk/version.py +1 -1
  419. ksadk_runtime_common/memory_backend/registry.py +56 -56
  420. ksadk_runtime_common/schemas/runtime_event_v1.json +95 -0
  421. ksadk_runtime_common/workspace_files/router.py +8 -2
  422. agentengine_sdk_python-0.7.0.dist-info/RECORD +0 -482
  423. ksadk/a2a/card_builder.py +0 -64
  424. ksadk/a2a/client.py +0 -309
  425. ksadk/runners/utils/langfuse.py +0 -230
  426. ksadk/server/static/assets/CodeBlock-P16VOLYi.js +0 -9
  427. ksadk/server/static/assets/MathMessageMarkdown-CdGiQWHR.js +0 -8
  428. ksadk/server/static/assets/MermaidBlock-IOcal8cm.js +0 -303
  429. ksadk/server/static/assets/NativeTerminalPanel-DGSDWsei.js +0 -1
  430. ksadk/server/static/assets/architecture-7EHR7CIX-BvUlsA6l.js +0 -1
  431. ksadk/server/static/assets/channel-CTuydARX.js +0 -1
  432. ksadk/server/static/assets/chunk-QZHKN3VN-BnCydivS.js +0 -1
  433. ksadk/server/static/assets/classDiagram-4FO5ZUOK-BNHg45Be.js +0 -1
  434. ksadk/server/static/assets/classDiagram-v2-Q7XG4LA2-BNHg45Be.js +0 -1
  435. ksadk/server/static/assets/eventmodeling-FCH6USID-DsAgWnlf.js +0 -1
  436. ksadk/server/static/assets/gitGraph-WXDBUCRP-BIao9Yjg.js +0 -1
  437. ksadk/server/static/assets/index-C00Lwg3L.js +0 -165
  438. ksadk/server/static/assets/index-DAURbCsP.css +0 -1
  439. ksadk/server/static/assets/info-J43DQDTF-CyipqGxU.js +0 -1
  440. ksadk/server/static/assets/packet-YPE3B663-CGkyRxlg.js +0 -1
  441. ksadk/server/static/assets/pie-LRSECV5Y-M0uWAf4n.js +0 -1
  442. ksadk/server/static/assets/radar-GUYGQ44K-Bdbm24-x.js +0 -1
  443. ksadk/server/static/assets/stateDiagram-v2-BHNVJYJU-8xBN_gLM.js +0 -1
  444. ksadk/server/static/assets/treeView-BLDUP644-npMo0ak1.js +0 -1
  445. ksadk/server/static/assets/treemap-LRROVOQU-CHdzrrdo.js +0 -1
  446. ksadk/server/static/assets/wardley-L42UT6IY-BEQz7wyy.js +0 -1
  447. ksadk/tracing/exporters/langfuse_exporter.py +0 -445
  448. {agentengine_sdk_python-0.7.0.dist-info → agentengine_sdk_python-0.8.1.dist-info}/entry_points.txt +0 -0
  449. {agentengine_sdk_python-0.7.0.dist-info → agentengine_sdk_python-0.8.1.dist-info}/licenses/LICENSE +0 -0
  450. {agentengine_sdk_python-0.7.0.dist-info → agentengine_sdk_python-0.8.1.dist-info}/top_level.txt +0 -0
ksadk/cli/cmd_hermes.py CHANGED
@@ -4,8 +4,9 @@ from __future__ import annotations
4
4
 
5
5
  import asyncio
6
6
  import os
7
+ from datetime import datetime, timezone
7
8
  from pathlib import Path
8
- from typing import Any, Callable, Optional
9
+ from typing import Any, Callable, Optional, cast
9
10
 
10
11
  import click
11
12
  from click.core import ParameterSource
@@ -14,9 +15,15 @@ from ksadk.api import AgentEngineClient
14
15
  from ksadk.cli.agent_ref import merge_agent_inputs, resolve_agent_ref
15
16
  from ksadk.cli.cmd_dashboard import _open_dashboard
16
17
  from ksadk.cli.dry_run import dry_run_option, effective_dry_run, run_async_with_dry_run
18
+ from ksadk.cli.env_options import (
19
+ apply_explicit_env_with_shell_priority,
20
+ env_options,
21
+ inject_env_to_environ,
22
+ resolve_runtime_env_overrides,
23
+ )
17
24
  from ksadk.cli.error_utils import remote_error, resolution_error
25
+ from ksadk.cli.model_catalog import fetch_provider_model_metadata
18
26
  from ksadk.cli.network_options import build_network_payload, network_cli_kwargs, network_options
19
- from ksadk.cli.storage import build_storage_config
20
27
  from ksadk.cli.resource_common import (
21
28
  CONTEXT_SETTINGS,
22
29
  ResourceActionSet,
@@ -32,37 +39,35 @@ from ksadk.cli.resource_common import (
32
39
  render_descriptor_list,
33
40
  render_descriptor_status,
34
41
  )
42
+ from ksadk.cli.storage import build_storage_config
35
43
  from ksadk.cli.ui import (
36
44
  emit_json,
37
45
  is_json_output,
38
- output_option as cli_output_option,
39
46
  print_info,
40
47
  print_kv,
41
- print_rule,
42
48
  print_success,
43
49
  print_title,
44
50
  print_warn,
45
51
  status_rich_style,
46
52
  )
53
+ from ksadk.cli.ui import (
54
+ output_option as cli_output_option,
55
+ )
56
+ from ksadk.configs.env_registry import is_sensitive_env_var
47
57
  from ksadk.deployment.agent_access import (
48
58
  get_latest_agent_access,
49
59
  is_agent_not_found_error,
50
60
  normalize_deployment_status,
51
61
  )
52
62
  from ksadk.deployment.state import clear_state, load_state, save_state
53
- from ksadk.cli.model_catalog import fetch_provider_model_metadata
54
- from ksadk.model_policy import build_runtime_model_policy_env
55
63
  from ksadk.hermes_terminal import (
56
64
  run_hermes_terminal_session,
57
- validate_hermes_exec_argv,
58
65
  validate_hermes_pairing_argv,
59
66
  )
67
+ from ksadk.model_policy import build_runtime_model_policy_env
60
68
 
61
-
62
- DEFAULT_HERMES_IMAGE = "ghcr.io/kingsoftcloud/hermes-agent:2026.5.29.2-ksadk-v1"
63
- DEFAULT_HERMES_CONTEXT_LENGTHS = (
64
- ("glm-5.1", "200000"),
65
- )
69
+ DEFAULT_HERMES_IMAGE = "ghcr.io/kingsoftcloud/hermes-agent:v2026.7.7.2-ksadk-v070"
70
+ DEFAULT_HERMES_CONTEXT_LENGTHS = (("glm-5.1", "200000"),)
66
71
  DEFAULT_HERMES_MODEL_NAME = "glm-5.2"
67
72
  DEFAULT_HERMES_PUBLIC_BASE_URL = "https://kspmas.ksyun.com/v1/"
68
73
  DEFAULT_HERMES_RUNTIME_BASE_URL = DEFAULT_HERMES_PUBLIC_BASE_URL
@@ -152,6 +157,7 @@ def _build_hermes_update_payload(
152
157
  "resources": payload["resources"],
153
158
  "scaling": payload["scaling"],
154
159
  "ui_config": payload["ui_config"],
160
+ "enable_observability": payload["enable_observability"],
155
161
  }
156
162
  if include_env:
157
163
  update_payload["env_vars"] = payload["env_vars"]
@@ -167,19 +173,6 @@ def hermes():
167
173
  """Hermes Agent 资源管理。"""
168
174
 
169
175
 
170
- def _load_dotenv_into_env(project_dir: Path) -> None:
171
- env_path = project_dir / ".env"
172
- if not env_path.exists():
173
- return
174
- try:
175
- from dotenv import dotenv_values
176
- except ImportError:
177
- return
178
- for key, value in dotenv_values(env_path).items():
179
- if key and value is not None and os.getenv(key) is None:
180
- os.environ[key] = str(value)
181
-
182
-
183
176
  def _get_hermes_global_env() -> dict[str, str]:
184
177
  global _HERMES_GLOBAL_ENV_CACHE
185
178
  if _HERMES_GLOBAL_ENV_CACHE is not None:
@@ -232,14 +225,17 @@ async def _fetch_hermes_bootstrap_config(region: str) -> dict[str, Any] | None:
232
225
 
233
226
  try:
234
227
  async with AgentEngineClient(region=region) as client:
235
- return await client.get_client_bootstrap_config(
236
- product="hermes",
237
- framework="hermes",
238
- region=region,
239
- client_type="cli",
240
- client_version=CLI_VERSION,
241
- locale=_env_value("LANG", "LC_ALL"),
242
- ignore_dry_run=True,
228
+ return cast(
229
+ dict[str, Any],
230
+ await client.get_client_bootstrap_config(
231
+ product="hermes",
232
+ framework="hermes",
233
+ region=region,
234
+ client_type="cli",
235
+ client_version=CLI_VERSION,
236
+ locale=_env_value("LANG", "LC_ALL"),
237
+ ignore_dry_run=True,
238
+ ),
243
239
  )
244
240
  except Exception as e:
245
241
  print_warn(f"拉取 Hermes 服务端默认配置失败,回退本地默认镜像: {e}")
@@ -272,6 +268,9 @@ def _build_hermes_env_vars(
272
268
  model_api_key: str | None = None,
273
269
  default_model: str | None = None,
274
270
  model_metadata: dict[str, Any] | None = None,
271
+ cli_env: dict[str, str] | None = None,
272
+ auto_dotenv: dict[str, str] | None = None,
273
+ shell_keys: set[str] | None = None,
275
274
  ) -> list[dict[str, Any]]:
276
275
  raw_model_base_url = model_base_url or _env_value("OPENAI_BASE_URL")
277
276
  resolved_model_base_url = (
@@ -279,7 +278,9 @@ def _build_hermes_env_vars(
279
278
  if raw_model_base_url
280
279
  else DEFAULT_HERMES_RUNTIME_BASE_URL
281
280
  )
282
- resolved_default_model = default_model or _env_value("OPENAI_MODEL_NAME") or DEFAULT_HERMES_MODEL_NAME
281
+ resolved_default_model = (
282
+ default_model or _env_value("OPENAI_MODEL_NAME") or DEFAULT_HERMES_MODEL_NAME
283
+ )
283
284
  metadata_context_length = ""
284
285
  if isinstance(model_metadata, dict):
285
286
  metadata_context_length = str(model_metadata.get("context_window_tokens") or "").strip()
@@ -307,28 +308,15 @@ def _build_hermes_env_vars(
307
308
  if fallback_model:
308
309
  raw["HERMES_FALLBACK_PROVIDER"] = _env_value("HERMES_FALLBACK_PROVIDER") or "custom"
309
310
  raw["HERMES_FALLBACK_MODEL"] = fallback_model
310
- raw["HERMES_FALLBACK_BASE_URL"] = _env_value("HERMES_FALLBACK_BASE_URL") or resolved_model_base_url
311
+ raw["HERMES_FALLBACK_BASE_URL"] = (
312
+ _env_value("HERMES_FALLBACK_BASE_URL") or resolved_model_base_url
313
+ )
311
314
  api_server_key = _env_value("API_SERVER_KEY", "HERMES_API_SERVER_KEY")
312
315
  if api_server_key:
313
316
  raw["API_SERVER_KEY"] = api_server_key
314
- langfuse_public_key = _env_value("HERMES_LANGFUSE_PUBLIC_KEY", "LANGFUSE_PUBLIC_KEY")
315
- langfuse_secret_key = _env_value("HERMES_LANGFUSE_SECRET_KEY", "LANGFUSE_SECRET_KEY")
316
- if langfuse_public_key and langfuse_secret_key:
317
- raw["HERMES_LANGFUSE_PUBLIC_KEY"] = langfuse_public_key
318
- raw["HERMES_LANGFUSE_SECRET_KEY"] = langfuse_secret_key
319
- langfuse_base_url = _env_value("HERMES_LANGFUSE_BASE_URL", "LANGFUSE_BASE_URL", "LANGFUSE_HOST")
320
- if langfuse_base_url:
321
- raw["HERMES_LANGFUSE_BASE_URL"] = langfuse_base_url
322
- for target_key, source_keys in {
323
- "HERMES_LANGFUSE_ENV": ("HERMES_LANGFUSE_ENV", "LANGFUSE_ENV"),
324
- "HERMES_LANGFUSE_RELEASE": ("HERMES_LANGFUSE_RELEASE", "LANGFUSE_RELEASE"),
325
- "HERMES_LANGFUSE_SAMPLE_RATE": ("HERMES_LANGFUSE_SAMPLE_RATE",),
326
- "HERMES_LANGFUSE_MAX_CHARS": ("HERMES_LANGFUSE_MAX_CHARS",),
327
- "HERMES_LANGFUSE_DEBUG": ("HERMES_LANGFUSE_DEBUG",),
328
- }.items():
329
- value = _env_value(*source_keys)
330
- if value:
331
- raw[target_key] = value
317
+ # Observability routes and credentials are platform-managed. The Hermes
318
+ # deploy CLI must not translate or forward legacy Langfuse SDK variables;
319
+ # server/runtime inject the standard OTLP primary and CloudMonitor secondary.
332
320
  for key in (
333
321
  "WPSXIEZUO_APP_ID",
334
322
  "WPSXIEZUO_APP_KEY",
@@ -344,10 +332,23 @@ def _build_hermes_env_vars(
344
332
  raw[key] = value
345
333
  raw = build_runtime_model_policy_env(raw, runtime="hermes")
346
334
  if raw.get("HERMES_FALLBACK_MODEL"):
347
- raw.setdefault("HERMES_FALLBACK_PROVIDER", _env_value("HERMES_FALLBACK_PROVIDER") or "custom")
348
- raw.setdefault("HERMES_FALLBACK_BASE_URL", _env_value("HERMES_FALLBACK_BASE_URL") or resolved_model_base_url)
335
+ raw.setdefault(
336
+ "HERMES_FALLBACK_PROVIDER", _env_value("HERMES_FALLBACK_PROVIDER") or "custom"
337
+ )
338
+ raw.setdefault(
339
+ "HERMES_FALLBACK_BASE_URL",
340
+ _env_value("HERMES_FALLBACK_BASE_URL") or resolved_model_base_url,
341
+ )
342
+ if cli_env or auto_dotenv:
343
+ apply_explicit_env_with_shell_priority(
344
+ raw, cli_env or {}, auto_dotenv or {}, shell_keys or set(os.environ)
345
+ )
349
346
  return [
350
- {"Key": key, "Value": str(value), "IsSensitive": any(token in key for token in ("KEY", "TOKEN", "SECRET"))}
347
+ {
348
+ "Key": key,
349
+ "Value": str(value),
350
+ "IsSensitive": is_sensitive_env_var(key),
351
+ }
351
352
  for key, value in raw.items()
352
353
  if value is not None and str(value).strip() != ""
353
354
  ]
@@ -384,9 +385,12 @@ def _diagnostic_field_style(status_value: str) -> str:
384
385
 
385
386
 
386
387
  def _flatten_agent_detail(agent: dict[str, Any]) -> dict[str, Any]:
387
- basic = agent.get("basic") if isinstance(agent.get("basic"), dict) else {}
388
- deployment = agent.get("deployment") if isinstance(agent.get("deployment"), dict) else {}
389
- quick = agent.get("quick_access") if isinstance(agent.get("quick_access"), dict) else {}
388
+ basic_value = agent.get("basic")
389
+ deployment_value = agent.get("deployment")
390
+ quick_value = agent.get("quick_access")
391
+ basic = basic_value if isinstance(basic_value, dict) else {}
392
+ deployment = deployment_value if isinstance(deployment_value, dict) else {}
393
+ quick = quick_value if isinstance(quick_value, dict) else {}
390
394
  return {
391
395
  "agent_id": basic.get("agent_id") or agent.get("agent_id"),
392
396
  "name": basic.get("name") or agent.get("name"),
@@ -395,17 +399,25 @@ def _flatten_agent_detail(agent: dict[str, Any]) -> dict[str, Any]:
395
399
  "message": basic.get("message") or "",
396
400
  "replicas": basic.get("replicas"),
397
401
  "ready_replicas": basic.get("ready_replicas"),
398
- "framework": deployment.get("framework") or basic.get("framework") or agent.get("framework"),
402
+ "framework": deployment.get("framework")
403
+ or basic.get("framework")
404
+ or agent.get("framework"),
399
405
  "region": basic.get("region") or agent.get("region"),
400
- "endpoint": quick.get("public_endpoint") or quick.get("private_endpoint") or agent.get("endpoint"),
406
+ "endpoint": quick.get("public_endpoint")
407
+ or quick.get("private_endpoint")
408
+ or agent.get("endpoint"),
401
409
  "api_key": quick.get("api_key") or agent.get("api_key"),
402
410
  "artifact_path": deployment.get("artifact_path") or agent.get("artifact_path"),
403
- "langfuse_url": (agent.get("advanced") or {}).get("observability_url") or agent.get("langfuse_trace_url") or "",
411
+ "langfuse_url": (agent.get("advanced") or {}).get("observability_url")
412
+ or agent.get("langfuse_trace_url")
413
+ or "",
404
414
  }
405
415
 
406
416
 
407
417
  def _resolve_hermes_ref(agent_ref: str | None) -> str:
408
- resolved = resolve_agent_ref(agent_ref, cwd=Path(".").resolve(), include_state=True, include_project_config=True)
418
+ resolved = resolve_agent_ref(
419
+ agent_ref, cwd=Path(".").resolve(), include_state=True, include_project_config=True
420
+ )
409
421
  if not resolved:
410
422
  raise resolution_error(
411
423
  HERMES_RESOURCE.missing_ref_message or "请指定 Hermes Agent。",
@@ -429,13 +441,19 @@ async def _get_hermes_detail_with_client(
429
441
  detail = _flatten_agent_detail(agent)
430
442
  framework = str(detail.get("framework") or "").strip().lower()
431
443
  if framework and framework != "hermes":
432
- raise resolution_error(f"目标 Agent 不是 Hermes: {agent_ref}", hints=["agentengine hermes list"])
444
+ raise resolution_error(
445
+ f"目标 Agent 不是 Hermes: {agent_ref}", hints=["agentengine hermes list"]
446
+ )
433
447
  return detail
434
448
 
435
449
 
436
- async def _get_hermes_detail(region: str, agent_ref: str, *, include_api_key: bool = False) -> dict[str, Any]:
450
+ async def _get_hermes_detail(
451
+ region: str, agent_ref: str, *, include_api_key: bool = False
452
+ ) -> dict[str, Any]:
437
453
  async with AgentEngineClient(region=region) as client:
438
- return await _get_hermes_detail_with_client(client, agent_ref, include_api_key=include_api_key)
454
+ return await _get_hermes_detail_with_client(
455
+ client, agent_ref, include_api_key=include_api_key
456
+ )
439
457
 
440
458
 
441
459
  def _resolve_hermes_access(
@@ -451,7 +469,9 @@ def _resolve_hermes_access(
451
469
  detail = asyncio.run(_get_hermes_detail(region, resolved, include_api_key=True))
452
470
  endpoint_value = str(detail.get("endpoint") or "").strip()
453
471
  if not endpoint_value:
454
- raise resolution_error("目标 Hermes Agent 未返回 Endpoint", hints=["agentengine hermes status <agent>"])
472
+ raise resolution_error(
473
+ "目标 Hermes Agent 未返回 Endpoint", hints=["agentengine hermes status <agent>"]
474
+ )
455
475
  return {
456
476
  "endpoint": endpoint_value,
457
477
  "api_key": api_key or detail.get("api_key"),
@@ -465,6 +485,13 @@ def _split_terminal_agent_ref_and_argv(
465
485
  *,
466
486
  validator: Callable[[tuple[str, ...] | list[str]], list[str]],
467
487
  ) -> tuple[str | None, list[str]]:
488
+ """Split argv into (agent_ref, exec_argv).
489
+
490
+ The first token is treated as agent_ref when the validator rejects the
491
+ full argv (whitelist validators raise ValueError), or when the validator
492
+ is the passthrough one and the first token looks like an agent id
493
+ (``ar-`` prefix) with remaining tokens.
494
+ """
468
495
  raw = [str(item) for item in argv]
469
496
  try:
470
497
  return None, validator(raw)
@@ -477,7 +504,22 @@ def _split_terminal_agent_ref_and_argv(
477
504
  raise direct_error
478
505
 
479
506
 
480
- def _render_hermes_dry_run(action: str, request: dict[str, Any], hints: tuple[str, ...] = ()) -> None:
507
+ def _passthrough_exec_argv(argv: tuple[str, ...] | list[str]) -> list[str]:
508
+ """Local exec passes argv through unchanged; the pod enforces allowlists.
509
+
510
+ Raises ValueError when the first token looks like an agent id (``ar-``
511
+ prefix) and there are remaining tokens, so ``_split_terminal_agent_ref_and_argv``
512
+ falls back to splitting the first token as agent_ref.
513
+ """
514
+ items = [str(item) for item in argv]
515
+ if len(items) >= 2 and items[0].startswith("ar-"):
516
+ raise ValueError("first token looks like an agent ref")
517
+ return items
518
+
519
+
520
+ def _render_hermes_dry_run(
521
+ action: str, request: dict[str, Any], hints: tuple[str, ...] = ()
522
+ ) -> None:
481
523
  if is_json_output():
482
524
  emit_json(
483
525
  build_dry_run_envelope(
@@ -511,6 +553,21 @@ def _render_hermes_dry_run(action: str, request: dict[str, Any], hints: tuple[st
511
553
  @click.option("--storage-size-gi", type=int, default=20, show_default=True, help="PVC 容量(Gi)")
512
554
  @click.option("--storage-mount-path", default=None, help="PVC 挂载目录(默认: /home/node/.hermes)")
513
555
  @click.option("--no-storage", is_flag=True, help="禁用默认 PVC 挂载")
556
+ @env_options
557
+ @click.option(
558
+ "--observability/--no-observability",
559
+ default=True,
560
+ help="是否启用可观测性 (默认开启)",
561
+ )
562
+ @click.option(
563
+ "--agent-id",
564
+ "agent_id_opt",
565
+ default=None,
566
+ help=(
567
+ "指定要更新的已有 Agent ID;当前凭证有权限时会自动回填 "
568
+ ".agentengine.state 并走热更新(用于本地状态丢失后重新关联)"
569
+ ),
570
+ )
514
571
  @network_options
515
572
  @dry_run_option()
516
573
  @cli_output_option()
@@ -526,6 +583,10 @@ def deploy(
526
583
  storage_size_gi: int,
527
584
  storage_mount_path: Optional[str],
528
585
  no_storage: bool,
586
+ extra_env: tuple[str, ...],
587
+ env_file: Optional[str],
588
+ observability: bool,
589
+ agent_id_opt: Optional[str],
529
590
  enable_public_access: Optional[bool],
530
591
  enable_vpc_access: bool,
531
592
  vpc_id: Optional[str],
@@ -541,6 +602,8 @@ def deploy(
541
602
  ctx = click.get_current_context(silent=True)
542
603
  include_env_on_update = any(
543
604
  (
605
+ bool(extra_env),
606
+ _option_was_explicit(ctx, "env_file"),
544
607
  _option_was_explicit(ctx, "model_base_url"),
545
608
  _option_was_explicit(ctx, "model_api_key"),
546
609
  _option_was_explicit(ctx, "default_model"),
@@ -566,8 +629,12 @@ def deploy(
566
629
  storage_size_gi=storage_size_gi,
567
630
  storage_mount_path=storage_mount_path,
568
631
  no_storage=no_storage,
632
+ observability=observability,
633
+ agent_id=agent_id_opt,
569
634
  include_env_on_update=include_env_on_update,
570
635
  include_storage_on_update=include_storage_on_update,
636
+ extra_env=extra_env,
637
+ env_file=env_file,
571
638
  **network_cli_kwargs(
572
639
  enable_public_access=enable_public_access,
573
640
  enable_vpc_access=enable_vpc_access,
@@ -597,22 +664,43 @@ async def _deploy_hermes(
597
664
  storage_size_gi: int,
598
665
  storage_mount_path: str | None,
599
666
  no_storage: bool,
667
+ observability: bool,
668
+ agent_id: str | None = None,
600
669
  include_env_on_update: bool,
601
670
  include_storage_on_update: bool,
602
- enable_public_access: bool | None,
603
- enable_vpc_access: bool,
604
- vpc_id: str | None,
605
- subnet_id: str | None,
606
- security_group_id: str | None,
607
- availability_zone: str | None,
608
- dry_run: bool,
671
+ extra_env: tuple[str, ...] = (),
672
+ env_file: str | None = None,
673
+ enable_public_access: bool | None = None,
674
+ enable_vpc_access: bool = False,
675
+ vpc_id: str | None = None,
676
+ subnet_id: str | None = None,
677
+ security_group_id: str | None = None,
678
+ availability_zone: str | None = None,
679
+ dry_run: bool = False,
609
680
  ) -> None:
610
681
  project_dir = Path(".").resolve()
611
- _load_dotenv_into_env(project_dir)
682
+ cli_env, auto_dotenv, shell_keys, env_source = resolve_runtime_env_overrides(
683
+ env_file=env_file,
684
+ extra_env=extra_env,
685
+ base_dir=project_dir,
686
+ )
687
+ loaded = inject_env_to_environ(cli_env, auto_dotenv, shell_keys)
688
+ if loaded:
689
+ print_info(f"已从 {env_source or '--env'} 注入环境变量: {loaded} 项")
690
+ if cli_env or auto_dotenv:
691
+ include_env_on_update = True
612
692
  state = load_state(project_dir)
613
693
  existing_agent_id = None
614
694
  if str(state.get("type") or state.get("framework") or "").strip().lower() == "hermes":
615
695
  existing_agent_id = str(state.get("agent_id") or "").strip() or None
696
+ explicit_agent_id = (agent_id or "").strip() or None
697
+ if explicit_agent_id:
698
+ if existing_agent_id and existing_agent_id != explicit_agent_id:
699
+ print_warn(
700
+ f"--agent-id ({explicit_agent_id}) 与本地状态 "
701
+ f"({existing_agent_id}) 不一致,以 --agent-id 为准"
702
+ )
703
+ existing_agent_id = explicit_agent_id
616
704
  agent_name = name or state.get("name") or project_dir.name.replace("-", "_")
617
705
  image_ref = image or _env_value("HERMES_IMAGE", "HERMES_DOCKER_IMAGE")
618
706
  if not image_ref:
@@ -626,7 +714,9 @@ async def _deploy_hermes(
626
714
  model_api_key=model_api_key,
627
715
  default_model=default_model,
628
716
  )
629
- resolved_default_model = default_model or _env_value("OPENAI_MODEL_NAME") or DEFAULT_HERMES_MODEL_NAME
717
+ resolved_default_model = (
718
+ default_model or _env_value("OPENAI_MODEL_NAME") or DEFAULT_HERMES_MODEL_NAME
719
+ )
630
720
  model_metadata = await fetch_provider_model_metadata(
631
721
  api_base=model_base_url or _env_value("OPENAI_BASE_URL"),
632
722
  api_key=model_api_key or _env_value("OPENAI_API_KEY"),
@@ -637,6 +727,9 @@ async def _deploy_hermes(
637
727
  model_api_key=model_api_key,
638
728
  default_model=default_model,
639
729
  model_metadata=model_metadata,
730
+ cli_env=cli_env,
731
+ auto_dotenv=auto_dotenv,
732
+ shell_keys=shell_keys,
640
733
  )
641
734
  payload = {
642
735
  "name": agent_name,
@@ -647,6 +740,7 @@ async def _deploy_hermes(
647
740
  "region": region,
648
741
  "resources": {"cpu": cpu, "memory": memory},
649
742
  "scaling": {"min_replicas": 1, "max_replicas": 1, "concurrency": 1000},
743
+ "enable_observability": observability,
650
744
  "env_vars": env_vars,
651
745
  "ui_config": {"profile": "hermes", "path": "/", "url": None},
652
746
  }
@@ -659,7 +753,9 @@ async def _deploy_hermes(
659
753
  if storage_config:
660
754
  payload["storage"] = storage_config
661
755
  if existing_agent_id and include_storage_on_update and no_storage:
662
- print_warn("更新已有 Hermes 时 `--no-storage` 不会删除服务端既有挂盘配置;默认保留已有配置。")
756
+ print_warn(
757
+ "更新已有 Hermes 时 `--no-storage` 不会删除服务端既有挂盘配置;默认保留已有配置。"
758
+ )
663
759
  network_payload = build_network_payload(
664
760
  enable_public_access=enable_public_access,
665
761
  enable_vpc_access=enable_vpc_access,
@@ -670,7 +766,7 @@ async def _deploy_hermes(
670
766
  region=region,
671
767
  dry_run=dry_run,
672
768
  )
673
- # create 默认开公网(network_payload 未显式 enable_public_access 时补 True);update 分支用原始 network_payload(None=保留现有配置)
769
+ # create 默认开公网;update 使用原始 payload,None 表示保留现有配置。
674
770
  create_network_payload = dict(network_payload) if network_payload is not None else {}
675
771
  if "enable_public_access" not in create_network_payload:
676
772
  create_network_payload["enable_public_access"] = True
@@ -682,6 +778,38 @@ async def _deploy_hermes(
682
778
  print_kv("镜像", image_ref)
683
779
 
684
780
  async with AgentEngineClient(region=region, dry_run=dry_run) as client:
781
+ if explicit_agent_id and not dry_run:
782
+ try:
783
+ detail = await client.get_agent(
784
+ explicit_agent_id, include_api_key=True
785
+ )
786
+ except Exception as e:
787
+ raise click.ClickException(
788
+ f"指定的 Agent ID '{explicit_agent_id}' 不存在,或当前凭证无权限访问。\n"
789
+ f" 详情: {e}\n"
790
+ " 👉 请确认 agent_id 正确,且当前 AK/SK / 账号有该 Agent 的权限。"
791
+ ) from e
792
+ qa = detail.get("quick_access", {}) or {}
793
+ basic = detail.get("basic", {}) or {}
794
+ recovered_state = state.copy()
795
+ recovered_state.update(
796
+ {
797
+ "agent_id": explicit_agent_id,
798
+ "name": basic.get("name") or agent_name,
799
+ "type": "hermes",
800
+ "region": region,
801
+ "endpoint": qa.get("public_endpoint"),
802
+ "updated_at": datetime.now(timezone.utc).isoformat(),
803
+ }
804
+ )
805
+ if qa.get("api_key"):
806
+ recovered_state["api_key"] = qa["api_key"]
807
+ recovered_state = {
808
+ k: v for k, v in recovered_state.items() if v is not None
809
+ }
810
+ save_state(project_dir, recovered_state)
811
+ state = recovered_state
812
+ print_info(f"已通过 --agent-id 关联已有 Agent: {explicit_agent_id}")
685
813
  if existing_agent_id:
686
814
  update_payload = _build_hermes_update_payload(
687
815
  payload=payload,
@@ -697,9 +825,7 @@ async def _deploy_hermes(
697
825
  raise
698
826
  # 本地 state 缓存的 agent_id 在服务端已不存在(已删除),
699
827
  # 清掉失效 state 后回退为新建,避免 404 卡住用户。
700
- print_warn(
701
- f"本地状态失效 ({existing_agent_id}),将自动回退为新建: {update_err}"
702
- )
828
+ print_warn(f"本地状态失效 ({existing_agent_id}),将自动回退为新建: {update_err}")
703
829
  cleared = clear_state(project_dir, key=existing_agent_id)
704
830
  if cleared:
705
831
  print_info("已清理失效的 .agentengine.state")
@@ -723,10 +849,12 @@ async def _deploy_hermes(
723
849
  attempts=12,
724
850
  interval_seconds=5,
725
851
  include_api_key=True,
726
- detail_fetcher=lambda agent_ref, include_api_key: _get_hermes_detail_with_client(
727
- client,
728
- agent_ref,
729
- include_api_key=include_api_key,
852
+ detail_fetcher=lambda agent_ref, include_api_key: (
853
+ _get_hermes_detail_with_client(
854
+ client,
855
+ agent_ref,
856
+ include_api_key=include_api_key,
857
+ )
730
858
  ),
731
859
  suppress_transient_not_found_log=True,
732
860
  )
@@ -753,10 +881,12 @@ async def _deploy_hermes(
753
881
  initial_delay_seconds=2,
754
882
  require_complete_access=True,
755
883
  include_api_key=True,
756
- detail_fetcher=lambda agent_ref, include_api_key: _get_hermes_detail_with_client(
757
- client,
758
- agent_ref,
759
- include_api_key=include_api_key,
884
+ detail_fetcher=lambda agent_ref, include_api_key: (
885
+ _get_hermes_detail_with_client(
886
+ client,
887
+ agent_ref,
888
+ include_api_key=include_api_key,
889
+ )
760
890
  ),
761
891
  suppress_transient_not_found_log=True,
762
892
  )
@@ -772,7 +902,7 @@ async def _deploy_hermes(
772
902
  if dry_run:
773
903
  return
774
904
 
775
- agent_id = res.get("agent_id")
905
+ final_agent_id = res.get("agent_id")
776
906
  endpoint = res.get("endpoint")
777
907
  api_key = res.get("api_key")
778
908
  deployment_status = normalize_deployment_status(res.get("status") or res.get("phase"))
@@ -781,7 +911,7 @@ async def _deploy_hermes(
781
911
  {
782
912
  "type": "hermes",
783
913
  "framework": "hermes",
784
- "agent_id": agent_id,
914
+ "agent_id": final_agent_id,
785
915
  "name": res.get("name") or agent_name,
786
916
  "region": region,
787
917
  "endpoint": endpoint,
@@ -792,13 +922,14 @@ async def _deploy_hermes(
792
922
  },
793
923
  )
794
924
  if is_json_output():
925
+ status_schema = HERMES_RESOURCE.status_schema
795
926
  emit_json(
796
927
  build_result_envelope(
797
928
  resource="hermes",
798
929
  action="deploy",
799
930
  result={
800
- "id": str(agent_id or ""),
801
- "agent_id": str(agent_id or ""),
931
+ "id": str(final_agent_id or ""),
932
+ "agent_id": str(final_agent_id or ""),
802
933
  "name": str(res.get("name") or agent_name),
803
934
  "status": deployment_status,
804
935
  "framework": "hermes",
@@ -808,12 +939,12 @@ async def _deploy_hermes(
808
939
  "ui_profile": "hermes",
809
940
  "ui_path": "/",
810
941
  },
811
- hints=list(HERMES_RESOURCE.status_schema.next_steps),
942
+ hints=list(status_schema.next_steps) if status_schema is not None else [],
812
943
  )
813
944
  )
814
945
  return
815
946
  print_success("Hermes 已提交部署")
816
- print_kv("Agent ID", str(agent_id or "(创建中)"))
947
+ print_kv("Agent ID", str(final_agent_id or "(创建中)"))
817
948
  print_kv("当前状态", deployment_status, value_style=status_rich_style(deployment_status))
818
949
  if endpoint:
819
950
  print_kv("Endpoint", str(endpoint), value_style="#58a6ff")
@@ -837,7 +968,9 @@ def list_hermes(region: str, page: int, size: int, dry_run: bool, output_mode: s
837
968
 
838
969
  async def _list():
839
970
  async with AgentEngineClient(region=region, dry_run=dry_run) as client:
840
- resp = await client.list_agents(region=region, framework="hermes", page=page, page_size=size)
971
+ resp = await client.list_agents(
972
+ region=region, framework="hermes", page=page, page_size=size
973
+ )
841
974
  agents = resp.get("agents", []) or []
842
975
  rows = []
843
976
  items = []
@@ -870,7 +1003,9 @@ def list_hermes(region: str, page: int, size: int, dry_run: bool, output_mode: s
870
1003
  items=items,
871
1004
  )
872
1005
 
873
- run_async_with_dry_run(_list(), dry_run=dry_run, dry_run_resource="hermes", dry_run_action="list")
1006
+ run_async_with_dry_run(
1007
+ _list(), dry_run=dry_run, dry_run_resource="hermes", dry_run_action="list"
1008
+ )
874
1009
 
875
1010
 
876
1011
  @hermes.command("status", context_settings=CONTEXT_SETTINGS)
@@ -897,40 +1032,50 @@ def status(agent_ref: Optional[str], region: str, dry_run: bool, output_mode: st
897
1032
  replicas = detail.get("replicas")
898
1033
  ready = detail.get("ready_replicas")
899
1034
  if replicas is not None or ready is not None:
900
- replicas_text = f"{ready if ready is not None else '-'}/{replicas if replicas is not None else '-'}"
1035
+ ready_text = ready if ready is not None else "-"
1036
+ replicas_total_text = replicas if replicas is not None else "-"
1037
+ replicas_text = f"{ready_text}/{replicas_total_text}"
901
1038
  replica_style = _diagnostic_field_style(status_value)
902
1039
  fields.append(("副本", replicas_text, replica_style))
903
1040
  if message:
904
1041
  message_style = _diagnostic_field_style(status_value)
905
1042
  fields.append(("消息", message, message_style))
906
- fields.extend([
907
- ("框架", str(detail.get("framework") or "-"), None),
908
- ("区域", str(detail.get("region") or region), None),
909
- ("Endpoint", str(detail.get("endpoint") or "-"), "#58a6ff"),
910
- ("Langfuse", str(detail.get("langfuse_url") or "-"), "#58a6ff" if detail.get("langfuse_url") else None),
911
- ("镜像", str(detail.get("artifact_path") or "-"), None),
912
- ])
1043
+ fields.extend(
1044
+ [
1045
+ ("框架", str(detail.get("framework") or "-"), None),
1046
+ ("区域", str(detail.get("region") or region), None),
1047
+ ("Endpoint", str(detail.get("endpoint") or "-"), "#58a6ff"),
1048
+ (
1049
+ "Langfuse",
1050
+ str(detail.get("langfuse_url") or "-"),
1051
+ "#58a6ff" if detail.get("langfuse_url") else None,
1052
+ ),
1053
+ ("镜像", str(detail.get("artifact_path") or "-"), None),
1054
+ ]
1055
+ )
913
1056
  render_descriptor_status(
914
1057
  HERMES_RESOURCE,
915
1058
  subtitle=str(detail.get("name") or resolved),
916
- fields=fields,
917
- item={
918
- "id": str(detail.get("agent_id") or "-"),
919
- "name": str(detail.get("name") or resolved),
1059
+ fields=fields,
1060
+ item={
1061
+ "id": str(detail.get("agent_id") or "-"),
1062
+ "name": str(detail.get("name") or resolved),
920
1063
  "status": status_value,
921
1064
  "framework": str(detail.get("framework") or "-"),
922
- "region": str(detail.get("region") or region),
923
- "endpoint": str(detail.get("endpoint") or "-"),
924
- "langfuse_url": str(detail.get("langfuse_url") or ""),
925
- "image": str(detail.get("artifact_path") or "-"),
926
- "message": message,
927
- "phase": str(detail.get("phase") or ""),
928
- "replicas": detail.get("replicas"),
929
- "ready_replicas": detail.get("ready_replicas"),
930
- },
931
- )
1065
+ "region": str(detail.get("region") or region),
1066
+ "endpoint": str(detail.get("endpoint") or "-"),
1067
+ "langfuse_url": str(detail.get("langfuse_url") or ""),
1068
+ "image": str(detail.get("artifact_path") or "-"),
1069
+ "message": message,
1070
+ "phase": str(detail.get("phase") or ""),
1071
+ "replicas": detail.get("replicas"),
1072
+ "ready_replicas": detail.get("ready_replicas"),
1073
+ },
1074
+ )
932
1075
 
933
- run_async_with_dry_run(_status(), dry_run=dry_run, dry_run_resource="hermes", dry_run_action="status")
1076
+ run_async_with_dry_run(
1077
+ _status(), dry_run=dry_run, dry_run_resource="hermes", dry_run_action="status"
1078
+ )
934
1079
 
935
1080
 
936
1081
  @hermes.command("open", context_settings=CONTEXT_SETTINGS)
@@ -965,11 +1110,8 @@ def open_hermes(
965
1110
  """打开 Hermes 管理 UI,或使用 --chat 打开统一聊天页。"""
966
1111
  _ = output_mode
967
1112
  ctx = click.get_current_context(silent=True)
968
- region_source = (
969
- ctx.get_parameter_source("region").name.lower()
970
- if ctx is not None and ctx.get_parameter_source("region") is not None
971
- else ""
972
- )
1113
+ parameter_source = ctx.get_parameter_source("region") if ctx is not None else None
1114
+ region_source = parameter_source.name.lower() if parameter_source is not None else ""
973
1115
  if manage and chat:
974
1116
  raise click.ClickException("--manage 与 --chat 不能同时使用")
975
1117
  try:
@@ -978,7 +1120,11 @@ def open_hermes(
978
1120
  raise click.ClickException(str(e)) from e
979
1121
  dry_run = effective_dry_run(dry_run)
980
1122
  target_path = ui_path or ("/chat" if chat else "/")
981
- parsed_expires = int(expires_seconds) if expires_seconds is not None and expires_seconds not in {"never", "forever"} else 0 if expires_seconds else None
1123
+ parsed_expires = (
1124
+ int(expires_seconds)
1125
+ if expires_seconds is not None and expires_seconds not in {"never", "forever"}
1126
+ else 0 if expires_seconds else None
1127
+ )
982
1128
  if dry_run:
983
1129
  _render_hermes_dry_run(
984
1130
  "open",
@@ -1013,6 +1159,7 @@ def open_hermes(
1013
1159
 
1014
1160
  @hermes.command("exec", context_settings=CONTEXT_SETTINGS)
1015
1161
  @click.argument("argv", nargs=-1, required=True)
1162
+ @click.option("--agent", "agent_option", default=None, help="Hermes Agent 名称(显式指定)")
1016
1163
  @click.option("--region", "-r", default="cn-beijing-6", envvar="KSYUN_REGION", help="区域")
1017
1164
  @click.option("--endpoint", "-e", default=None, help="Agent Endpoint URL (覆盖自动获取)")
1018
1165
  @click.option("--api-key", default=None, help="AgentEngine API Key (覆盖自动获取)")
@@ -1022,6 +1169,7 @@ def open_hermes(
1022
1169
  @cli_output_option()
1023
1170
  def exec_hermes(
1024
1171
  argv: tuple[str, ...],
1172
+ agent_option: Optional[str],
1025
1173
  region: str,
1026
1174
  endpoint: Optional[str],
1027
1175
  api_key: Optional[str],
@@ -1033,10 +1181,19 @@ def exec_hermes(
1033
1181
  """透传受限 Hermes 只读运维子命令。"""
1034
1182
  _ = output_mode
1035
1183
  try:
1036
- agent_ref, validated_argv = _split_terminal_agent_ref_and_argv(
1184
+ if agent_option is not None:
1185
+ agent_option = agent_option.strip()
1186
+ if not agent_option:
1187
+ raise click.ClickException("--agent 必须指定非空的 Hermes Agent 名称")
1188
+ positional_agent_ref, validated_argv = _split_terminal_agent_ref_and_argv(
1037
1189
  argv,
1038
- validator=validate_hermes_exec_argv,
1190
+ validator=_passthrough_exec_argv,
1039
1191
  )
1192
+ if agent_option is not None and positional_agent_ref:
1193
+ raise click.ClickException(
1194
+ "--agent 不能与位置参数 Agent ID 同时使用: " f"{positional_agent_ref}"
1195
+ )
1196
+ agent_ref = agent_option if agent_option is not None else positional_agent_ref
1040
1197
  dry_run = effective_dry_run(dry_run)
1041
1198
  if dry_run:
1042
1199
  _render_hermes_dry_run(
@@ -1052,7 +1209,9 @@ def exec_hermes(
1052
1209
  hints=("dry-run 未解析远端 Agent,也未建立 websocket。",),
1053
1210
  )
1054
1211
  return
1055
- access = _resolve_hermes_access(agent_ref=agent_ref, region=region, endpoint=endpoint, api_key=api_key)
1212
+ access = _resolve_hermes_access(
1213
+ agent_ref=agent_ref, region=region, endpoint=endpoint, api_key=api_key
1214
+ )
1056
1215
  exit_code = asyncio.run(
1057
1216
  run_hermes_terminal_session(
1058
1217
  endpoint=str(access["endpoint"]),
@@ -1061,6 +1220,7 @@ def exec_hermes(
1061
1220
  insecure=insecure,
1062
1221
  mode="exec",
1063
1222
  argv=validated_argv,
1223
+ exec_argv_validator=_passthrough_exec_argv,
1064
1224
  )
1065
1225
  )
1066
1226
  except (KeyboardInterrupt, asyncio.CancelledError):
@@ -1116,7 +1276,9 @@ def pairing_hermes(
1116
1276
  hints=("dry-run 未解析远端 Agent,也未建立 websocket。",),
1117
1277
  )
1118
1278
  return
1119
- access = _resolve_hermes_access(agent_ref=agent_ref, region=region, endpoint=endpoint, api_key=api_key)
1279
+ access = _resolve_hermes_access(
1280
+ agent_ref=agent_ref, region=region, endpoint=endpoint, api_key=api_key
1281
+ )
1120
1282
  exit_code = asyncio.run(
1121
1283
  run_hermes_terminal_session(
1122
1284
  endpoint=str(access["endpoint"]),
@@ -1172,7 +1334,9 @@ def connect_hermes(
1172
1334
  return
1173
1335
 
1174
1336
  try:
1175
- access = _resolve_hermes_access(agent_ref=agent_ref, region=region, endpoint=endpoint, api_key=api_key)
1337
+ access = _resolve_hermes_access(
1338
+ agent_ref=agent_ref, region=region, endpoint=endpoint, api_key=api_key
1339
+ )
1176
1340
  exit_code = asyncio.run(
1177
1341
  run_hermes_terminal_session(
1178
1342
  endpoint=str(access["endpoint"]),
@@ -1217,7 +1381,9 @@ def _delete_impl(agent_refs: tuple[str, ...], region: str, assume_yes: bool, dry
1217
1381
  raise remote_error(f"以下 Hermes 删除失败: {', '.join(failed)}")
1218
1382
  return {"targets": list(agent_refs), "deleted": deleted, "failed": failed}
1219
1383
 
1220
- result = run_async_with_dry_run(_delete(), dry_run=dry_run, dry_run_resource="hermes", dry_run_action="delete")
1384
+ result = run_async_with_dry_run(
1385
+ _delete(), dry_run=dry_run, dry_run_resource="hermes", dry_run_action="delete"
1386
+ )
1221
1387
  if result is not None:
1222
1388
  deleted_text = ", ".join(result["deleted"]) or "-"
1223
1389
  failed_text = ", ".join(result["failed"]) or "-"
@@ -1245,7 +1411,13 @@ def _delete_impl(agent_refs: tuple[str, ...], region: str, assume_yes: bool, dry
1245
1411
  @confirm_options()
1246
1412
  @dry_run_option()
1247
1413
  @cli_output_option()
1248
- def delete(agent_refs: tuple[str, ...], region: str, assume_yes: bool, dry_run: bool, output_mode: str | None):
1414
+ def delete(
1415
+ agent_refs: tuple[str, ...],
1416
+ region: str,
1417
+ assume_yes: bool,
1418
+ dry_run: bool,
1419
+ output_mode: str | None,
1420
+ ):
1249
1421
  """删除 Hermes Agent。"""
1250
1422
  _ = output_mode
1251
1423
  _delete_impl(agent_refs=agent_refs, region=region, assume_yes=assume_yes, dry_run=dry_run)
@@ -1257,7 +1429,13 @@ def delete(agent_refs: tuple[str, ...], region: str, assume_yes: bool, dry_run:
1257
1429
  @confirm_options()
1258
1430
  @dry_run_option()
1259
1431
  @cli_output_option()
1260
- def destroy(agent_refs: tuple[str, ...], region: str, assume_yes: bool, dry_run: bool, output_mode: str | None):
1432
+ def destroy(
1433
+ agent_refs: tuple[str, ...],
1434
+ region: str,
1435
+ assume_yes: bool,
1436
+ dry_run: bool,
1437
+ output_mode: str | None,
1438
+ ):
1261
1439
  """删除 Hermes Agent。"""
1262
1440
  _ = output_mode
1263
1441
  _delete_impl(agent_refs=agent_refs, region=region, assume_yes=assume_yes, dry_run=dry_run)