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
@@ -0,0 +1,1122 @@
1
+ """Space-scoped A2A discovery and authorized data-plane calls."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import hashlib
6
+ import json
7
+ import logging
8
+ import os
9
+ import uuid
10
+ from collections.abc import AsyncIterator, Mapping
11
+ from contextlib import AsyncExitStack, asynccontextmanager
12
+ from dataclasses import dataclass
13
+ from datetime import datetime, timezone
14
+ from http.cookies import CookieError, SimpleCookie
15
+ from typing import Any
16
+ from urllib.parse import parse_qsl, urlencode, urlsplit, urlunsplit
17
+
18
+ import httpx
19
+ from a2a.client import ClientCallContext, ClientConfig, create_client
20
+ from a2a.types import (
21
+ AgentCard,
22
+ CancelTaskRequest,
23
+ GetTaskRequest,
24
+ Message,
25
+ Part,
26
+ Role,
27
+ SendMessageConfiguration,
28
+ SendMessageRequest,
29
+ SubscribeToTaskRequest,
30
+ TaskState,
31
+ )
32
+ from google.protobuf.json_format import MessageToDict, ParseDict
33
+
34
+ from ksadk.a2a.control_plane import (
35
+ A2AAgentCardClient,
36
+ A2AControlPlane,
37
+ A2ARouteInterface,
38
+ CredentialInjection,
39
+ DiscoveredAgent,
40
+ PreparedA2AOperation,
41
+ SpaceAgentPage,
42
+ )
43
+ from ksadk.a2a.event_adapter import A2AEventAdapter
44
+ from ksadk.a2a.external_transport import A2AExternalTransport
45
+ from ksadk.a2a.ids import require_a2a_resource_id
46
+ from ksadk.a2a.task_event_dispatcher import A2ATaskEventDispatcher
47
+ from ksadk.a2a.task_event_outbox import (
48
+ A2ATaskEventOutbox,
49
+ InMemoryA2ATaskEventOutbox,
50
+ SQLiteA2ATaskEventOutbox,
51
+ )
52
+ from ksadk.events.runtime_event import RuntimeEvent
53
+
54
+ logger = logging.getLogger(__name__)
55
+
56
+ ENV_A2A_SPACE_ID = "KSADK_A2A_SPACE_ID"
57
+ ENV_A2A_SPACE_IDS = "KSADK_A2A_SPACE_IDS"
58
+ ENV_A2A_ENABLE_PUBLIC_EGRESS = "KSADK_A2A_ENABLE_PUBLIC_EGRESS"
59
+
60
+ ERR_PUBLIC_EGRESS_DISABLED = "A2A_PUBLIC_EGRESS_DISABLED"
61
+ MAX_A2A_MESSAGE_BYTES = 1024 * 1024
62
+ MAX_A2A_MESSAGE_PARTS = 64
63
+ MAX_A2A_MESSAGE_ID_LENGTH = 128
64
+
65
+
66
+ def _require_opaque_space_id(value: str, *, field_name: str) -> str:
67
+ """Validate a server-issued opaque Space ID without assuming a prefix."""
68
+ normalized = str(value or "").strip()
69
+ if not normalized or len(normalized) > 256 or any(char.isspace() for char in normalized):
70
+ raise ValueError(f"{field_name} must be a non-empty opaque resource ID")
71
+ return normalized
72
+
73
+
74
+ @dataclass(frozen=True)
75
+ class A2APlatformTask:
76
+ """AgentEngine task locator with an optional latest remote A2A snapshot."""
77
+
78
+ id: str
79
+ remote_task: Any | None = None
80
+
81
+
82
+ def _utc_now() -> str:
83
+ return datetime.now(timezone.utc).isoformat().replace("+00:00", "Z")
84
+
85
+
86
+ def _canonical_proto(value: Any) -> dict[str, Any]:
87
+ return MessageToDict(value, preserving_proto_field_name=False)
88
+
89
+
90
+ def _canonical_sha256(value: Any) -> str:
91
+ payload = _canonical_proto(value)
92
+ encoded = json.dumps(payload, ensure_ascii=False, sort_keys=True, separators=(",", ":"))
93
+ return hashlib.sha256(encoded.encode("utf-8")).hexdigest()
94
+
95
+
96
+ def _present_message_field(value: Any, field_name: str) -> Any | None:
97
+ has_field = getattr(value, "HasField", None)
98
+ if callable(has_field):
99
+ try:
100
+ if not has_field(field_name):
101
+ return None
102
+ except ValueError:
103
+ pass
104
+ return getattr(value, field_name, None)
105
+
106
+
107
+ class A2ASpaceClient:
108
+ """Discovers Space members and performs permit-authorized A2A calls."""
109
+
110
+ def __init__(
111
+ self,
112
+ space_id: str,
113
+ backend: A2AControlPlane,
114
+ *,
115
+ egress_enabled: bool = False,
116
+ httpx_client: httpx.AsyncClient | None = None,
117
+ external_transport: A2AExternalTransport | None = None,
118
+ event_sink: Any | None = None,
119
+ event_outbox: A2ATaskEventOutbox | None = None,
120
+ event_dispatcher: A2ATaskEventDispatcher | None = None,
121
+ ) -> None:
122
+ space_id = _require_opaque_space_id(space_id, field_name="space_id")
123
+ if external_transport is not None and not isinstance(
124
+ external_transport, A2AExternalTransport
125
+ ):
126
+ raise TypeError("external_transport must implement A2AExternalTransport")
127
+ self._space_id = space_id
128
+ self._backend = backend
129
+ self._egress_enabled = egress_enabled
130
+ self._httpx_client = httpx_client
131
+ self._external_transport = external_transport
132
+ self._event_sink = event_sink
133
+ if event_dispatcher is not None and event_outbox is not None:
134
+ raise ValueError("pass either event_dispatcher or event_outbox, not both")
135
+ self._owns_event_dispatcher = event_dispatcher is None
136
+ self._event_dispatcher = event_dispatcher or A2ATaskEventDispatcher(
137
+ event_outbox or InMemoryA2ATaskEventOutbox(),
138
+ backend,
139
+ )
140
+ self._event_adapter = A2AEventAdapter()
141
+ self._agents_by_id: dict[str, DiscoveredAgent] = {}
142
+ self._agents_by_task: dict[str, DiscoveredAgent] = {}
143
+ self._seq = 0
144
+ self._persisted_wire_events: set[str] = set()
145
+
146
+ @classmethod
147
+ def from_env(
148
+ cls,
149
+ *,
150
+ space_id: str | None = None,
151
+ backend: A2AControlPlane | None = None,
152
+ httpx_client: httpx.AsyncClient | None = None,
153
+ external_transport: A2AExternalTransport | None = None,
154
+ egress_enabled: bool | None = None,
155
+ event_sink: Any | None = None,
156
+ event_outbox: A2ATaskEventOutbox | None = None,
157
+ event_dispatcher: A2ATaskEventDispatcher | None = None,
158
+ ) -> "A2ASpaceClient":
159
+ selected_space_id = str(
160
+ space_id or os.getenv(ENV_A2A_SPACE_ID) or ""
161
+ ).strip()
162
+ if selected_space_id:
163
+ selected_space_id = _require_opaque_space_id(
164
+ selected_space_id, field_name="space_id"
165
+ )
166
+ else:
167
+ raw_space_ids = str(os.getenv(ENV_A2A_SPACE_IDS) or "").strip()
168
+ if not raw_space_ids:
169
+ raise ValueError(
170
+ f"missing {ENV_A2A_SPACE_ID} and {ENV_A2A_SPACE_IDS}; pass space_id "
171
+ "or add the Runtime Agent to an A2A Space first"
172
+ )
173
+ try:
174
+ configured_space_ids = json.loads(raw_space_ids)
175
+ except json.JSONDecodeError as exc:
176
+ raise ValueError(f"{ENV_A2A_SPACE_IDS} must be a JSON string array") from exc
177
+ if not isinstance(configured_space_ids, list) or not configured_space_ids:
178
+ raise ValueError(f"{ENV_A2A_SPACE_IDS} must be a non-empty JSON string array")
179
+ if len(configured_space_ids) > 100:
180
+ raise ValueError(f"{ENV_A2A_SPACE_IDS} cannot contain more than 100 Space IDs")
181
+ normalized_space_ids: list[str] = []
182
+ for index, configured_space_id in enumerate(configured_space_ids):
183
+ if not isinstance(configured_space_id, str):
184
+ raise ValueError(f"{ENV_A2A_SPACE_IDS}[{index}] must be an A2A Space ID string")
185
+ normalized = configured_space_id.strip()
186
+ normalized = _require_opaque_space_id(
187
+ normalized, field_name=f"{ENV_A2A_SPACE_IDS}[{index}]"
188
+ )
189
+ normalized_space_ids.append(normalized)
190
+ if len(set(normalized_space_ids)) != len(normalized_space_ids):
191
+ raise ValueError(f"{ENV_A2A_SPACE_IDS} must not contain duplicate Space IDs")
192
+ if len(normalized_space_ids) != 1:
193
+ raise ValueError(
194
+ f"{ENV_A2A_SPACE_IDS} contains multiple Space IDs; pass space_id explicitly"
195
+ )
196
+ selected_space_id = normalized_space_ids[0]
197
+ if backend is None:
198
+ from ksadk.a2a.service_env import (
199
+ resolve_a2a_service_token,
200
+ resolve_a2a_service_url,
201
+ )
202
+ service_url = resolve_a2a_service_url()
203
+ if not service_url:
204
+ raise ValueError(
205
+ "A2A service url not configured: set KSADK_A2A_SERVICE_URL or AICP env"
206
+ )
207
+ backend = A2AAgentCardClient(
208
+ service_url,
209
+ service_token=resolve_a2a_service_token(),
210
+ httpx_client=httpx_client,
211
+ )
212
+ if egress_enabled is None:
213
+ raw_egress = os.getenv(ENV_A2A_ENABLE_PUBLIC_EGRESS) or ""
214
+ egress_enabled = raw_egress.strip().lower() in {"1", "true", "yes", "on"}
215
+ if event_outbox is None and event_dispatcher is None:
216
+ event_outbox = SQLiteA2ATaskEventOutbox()
217
+ return cls(
218
+ selected_space_id,
219
+ backend,
220
+ egress_enabled=egress_enabled,
221
+ httpx_client=httpx_client,
222
+ external_transport=external_transport,
223
+ event_sink=event_sink,
224
+ event_outbox=event_outbox,
225
+ event_dispatcher=event_dispatcher,
226
+ )
227
+
228
+ async def discover(
229
+ self,
230
+ prompt: str | None = None,
231
+ *,
232
+ skill: str | None = None,
233
+ include_blocked: bool = False,
234
+ ) -> list[DiscoveredAgent]:
235
+ page = await self._backend.list_space_agents(
236
+ self._space_id,
237
+ prompt=prompt,
238
+ skill_id=skill,
239
+ include_blocked=include_blocked,
240
+ )
241
+ for agent in page.agents:
242
+ require_a2a_resource_id(
243
+ agent.agent_id,
244
+ "a2a-agent-",
245
+ field_name="DiscoveredAgent.agent_id",
246
+ )
247
+ require_a2a_resource_id(
248
+ agent.version_id,
249
+ "a2a-version-",
250
+ field_name="DiscoveredAgent.version_id",
251
+ )
252
+ self._agents_by_id[agent.agent_id] = agent
253
+ return page.agents
254
+
255
+ def _check_egress(self, agent: DiscoveredAgent) -> None:
256
+ if agent.route_kind == "external_public" and not self._egress_enabled:
257
+ raise PermissionError(
258
+ f"{ERR_PUBLIC_EGRESS_DISABLED}: external Agent {agent.agent_id} requires "
259
+ "Network.EnablePublicAccess"
260
+ )
261
+
262
+ @property
263
+ def event_dispatcher(self) -> A2ATaskEventDispatcher:
264
+ """Runtime-scoped task event dispatcher used by this client."""
265
+
266
+ return self._event_dispatcher
267
+
268
+ async def aclose(self, *, flush_timeout_seconds: float = 5.0) -> None:
269
+ """Stop the dispatcher only when this standalone client created it."""
270
+
271
+ if self._owns_event_dispatcher:
272
+ await self._event_dispatcher.stop(flush_timeout_seconds=flush_timeout_seconds)
273
+
274
+ async def __aenter__(self) -> "A2ASpaceClient":
275
+ return self
276
+
277
+ async def __aexit__(self, *args: Any) -> None:
278
+ await self.aclose()
279
+
280
+ async def _resolve_agent(self, agent_id: str) -> DiscoveredAgent:
281
+ agent = self._agents_by_id.get(agent_id)
282
+ if agent is None:
283
+ await self.discover()
284
+ agent = self._agents_by_id.get(agent_id)
285
+ if agent is None:
286
+ raise KeyError(f"Agent {agent_id!r} is not discoverable in Space {self._space_id}")
287
+ self._check_egress(agent)
288
+ return agent
289
+
290
+ async def send_message(
291
+ self,
292
+ agent_id: str,
293
+ message: str | Message,
294
+ *,
295
+ return_immediately: bool = False,
296
+ idempotency_token: str | None = None,
297
+ ) -> A2APlatformTask:
298
+ agent = await self._resolve_agent(agent_id)
299
+ normalized = self._normalize_initial_message(message)
300
+ prepared = await self._backend.prepare_call(
301
+ space_id=self._space_id,
302
+ target_agent_id=agent.agent_id,
303
+ expected_version_id=agent.version_id,
304
+ message_id=normalized.message_id,
305
+ message_sha256=_canonical_sha256(normalized),
306
+ idempotency_token=idempotency_token or f"idem-{uuid.uuid4().hex}",
307
+ )
308
+ self._validate_prepared_target(agent, prepared)
309
+ handle = await self._send_prepared_message(
310
+ prepared,
311
+ agent,
312
+ normalized,
313
+ return_immediately=return_immediately,
314
+ )
315
+ self._agents_by_task[prepared.platform_task_id] = agent
316
+ await self._record_agent_for_task(prepared.platform_task_id, agent)
317
+ return handle
318
+
319
+ async def continue_task(
320
+ self,
321
+ task_id: str,
322
+ message: str | Message,
323
+ *,
324
+ return_immediately: bool = False,
325
+ idempotency_token: str | None = None,
326
+ ) -> A2APlatformTask:
327
+ require_a2a_resource_id(task_id, "a2a-task-", field_name="task_id")
328
+ normalized = self._normalize_initial_message(message)
329
+ prepared = await self._backend.prepare_task_operation(
330
+ platform_task_id=task_id,
331
+ operation="send_message",
332
+ message_id=normalized.message_id,
333
+ message_sha256=_canonical_sha256(normalized),
334
+ idempotency_token=idempotency_token or f"idem-{uuid.uuid4().hex}",
335
+ )
336
+ self._validate_prepared_ids(prepared)
337
+ remote_task = self._require_remote_task(prepared)
338
+ normalized.task_id = remote_task.remote_task_id
339
+ if remote_task.remote_context_id:
340
+ normalized.context_id = remote_task.remote_context_id
341
+ agent = self._agent_from_prepared(prepared)
342
+ return await self._send_prepared_message(
343
+ prepared,
344
+ agent,
345
+ normalized,
346
+ return_immediately=return_immediately,
347
+ )
348
+
349
+ async def _send_prepared_message(
350
+ self,
351
+ prepared: PreparedA2AOperation,
352
+ agent: DiscoveredAgent,
353
+ message: Message,
354
+ *,
355
+ return_immediately: bool,
356
+ ) -> A2APlatformTask:
357
+ first_task = None
358
+ remote_task_id = prepared.remote_task.remote_task_id if prepared.remote_task else None
359
+ remote_context_id = prepared.remote_task.remote_context_id if prepared.remote_task else None
360
+ operation_instance_id = self._operation_instance_id(prepared)
361
+ async with self._operation_client(agent, prepared) as (client, context):
362
+ request = SendMessageRequest(
363
+ message=message,
364
+ configuration=SendMessageConfiguration(return_immediately=return_immediately),
365
+ )
366
+ wire_position = 0
367
+ async for response in client.send_message(request, context=context):
368
+ response_task = _present_message_field(response, "task")
369
+ if response_task is not None and str(getattr(response_task, "id", None) or ""):
370
+ # 跟踪最新 task 状态:每个带 task 的 response 都更新 first_task,
371
+ # 使 send_message 返回的是最终状态(如 COMPLETED)而非首个 SUBMITTED。
372
+ first_task = response_task
373
+ observed_task_id = str(response_task.id)
374
+ observed_context_id = str(response_task.context_id or "") or None
375
+ if remote_task_id is None:
376
+ await self._bind_task(prepared.platform_task_id, response_task)
377
+ elif (remote_task_id, remote_context_id) != (
378
+ observed_task_id,
379
+ observed_context_id,
380
+ ):
381
+ raise RuntimeError("A2A_REMOTE_BINDING_CONFLICT")
382
+ remote_task_id = observed_task_id
383
+ remote_context_id = observed_context_id
384
+ if remote_task_id is not None:
385
+ self._validate_remote_task_observation(
386
+ remote_task_id,
387
+ remote_context_id,
388
+ response,
389
+ )
390
+ await self._project_stream_item(
391
+ prepared.platform_task_id,
392
+ response,
393
+ agent,
394
+ wire_position=wire_position,
395
+ operation_instance_id=operation_instance_id,
396
+ )
397
+ wire_position += 1
398
+ if return_immediately and first_task is not None:
399
+ break
400
+ return A2APlatformTask(
401
+ id=prepared.platform_task_id,
402
+ remote_task=first_task,
403
+ )
404
+
405
+ async def subscribe(self, task_id: str):
406
+ require_a2a_resource_id(task_id, "a2a-task-", field_name="task_id")
407
+ prepared = await self._backend.prepare_task_operation(
408
+ platform_task_id=task_id,
409
+ operation="subscribe_to_task",
410
+ )
411
+ self._validate_prepared_ids(prepared)
412
+ agent = self._agent_from_prepared(prepared)
413
+ async for item, _ in self._iter_subscription(prepared, agent):
414
+ yield item
415
+
416
+ async def _iter_subscription(
417
+ self,
418
+ prepared: PreparedA2AOperation,
419
+ agent: DiscoveredAgent,
420
+ ):
421
+ remote_task = self._require_remote_task(prepared)
422
+ operation_instance_id = self._operation_instance_id(prepared)
423
+ async with self._operation_client(agent, prepared) as (client, context):
424
+ wire_position = 0
425
+ async for event in client.subscribe(
426
+ SubscribeToTaskRequest(id=remote_task.remote_task_id),
427
+ context=context,
428
+ ):
429
+ self._validate_remote_task_observation(
430
+ remote_task.remote_task_id,
431
+ remote_task.remote_context_id,
432
+ event,
433
+ )
434
+ persisted = await self._project_stream_item(
435
+ prepared.platform_task_id,
436
+ event,
437
+ agent,
438
+ wire_position=wire_position,
439
+ operation_instance_id=operation_instance_id,
440
+ )
441
+ wire_position += 1
442
+ yield event, persisted
443
+
444
+ async def cancel(
445
+ self,
446
+ task_id: str,
447
+ *,
448
+ idempotency_token: str | None = None,
449
+ ) -> A2APlatformTask:
450
+ require_a2a_resource_id(task_id, "a2a-task-", field_name="task_id")
451
+ prepared = await self._backend.prepare_task_operation(
452
+ platform_task_id=task_id,
453
+ operation="cancel_task",
454
+ idempotency_token=idempotency_token or f"idem-{uuid.uuid4().hex}",
455
+ )
456
+ self._validate_prepared_ids(prepared)
457
+ remote_task_ref = self._require_remote_task(prepared)
458
+ agent = self._agent_from_prepared(prepared)
459
+ async with self._operation_client(agent, prepared) as (client, context):
460
+ remote_task = await client.cancel_task(
461
+ CancelTaskRequest(id=remote_task_ref.remote_task_id), context=context
462
+ )
463
+ self._validate_remote_task_observation(
464
+ remote_task_ref.remote_task_id,
465
+ remote_task_ref.remote_context_id,
466
+ remote_task,
467
+ )
468
+ await self._project_stream_item(
469
+ task_id,
470
+ remote_task,
471
+ agent,
472
+ wire_position=0,
473
+ operation_instance_id=self._operation_instance_id(prepared),
474
+ )
475
+ return A2APlatformTask(
476
+ id=task_id,
477
+ remote_task=remote_task,
478
+ )
479
+
480
+ async def get_task(self, task_id: str) -> A2APlatformTask:
481
+ require_a2a_resource_id(task_id, "a2a-task-", field_name="task_id")
482
+ cached_agent = self._agents_by_task.get(task_id)
483
+ prepared = await self._backend.prepare_task_operation(
484
+ platform_task_id=task_id,
485
+ operation="get_task",
486
+ agent_id=getattr(cached_agent, "agent_id", None),
487
+ )
488
+ self._validate_prepared_ids(prepared)
489
+ remote_task_ref = self._require_remote_task(prepared)
490
+ agent = self._agent_from_prepared(prepared)
491
+ async with self._operation_client(agent, prepared) as (client, context):
492
+ remote_task = await client.get_task(
493
+ GetTaskRequest(id=remote_task_ref.remote_task_id), context=context
494
+ )
495
+ self._validate_remote_task_observation(
496
+ remote_task_ref.remote_task_id,
497
+ remote_task_ref.remote_context_id,
498
+ remote_task,
499
+ )
500
+ await self._project_stream_item(
501
+ task_id,
502
+ remote_task,
503
+ agent,
504
+ wire_position=0,
505
+ operation_instance_id=self._operation_instance_id(prepared),
506
+ )
507
+ return A2APlatformTask(
508
+ id=task_id,
509
+ remote_task=remote_task,
510
+ )
511
+
512
+ def _normalize_initial_message(self, message: str | Message) -> Message:
513
+ if isinstance(message, str):
514
+ message = Message(
515
+ role=Role.ROLE_USER,
516
+ parts=[Part(text=message)],
517
+ message_id=f"message-{uuid.uuid4().hex}",
518
+ )
519
+ if getattr(message, "task_id", "") or getattr(message, "context_id", ""):
520
+ raise ValueError("caller must not provide remote task_id/context_id")
521
+ if message.role != Role.ROLE_USER:
522
+ raise ValueError("A2A Message role must be user")
523
+ if not 1 <= len(message.parts) <= MAX_A2A_MESSAGE_PARTS:
524
+ raise ValueError("A2A Message parts must contain 1-64 items")
525
+ if not getattr(message, "message_id", ""):
526
+ message.message_id = f"message-{uuid.uuid4().hex}"
527
+ if len(message.message_id) > MAX_A2A_MESSAGE_ID_LENGTH:
528
+ raise ValueError("A2A Message message_id must contain 1-128 characters")
529
+ encoded = json.dumps(
530
+ _canonical_proto(message),
531
+ ensure_ascii=False,
532
+ sort_keys=True,
533
+ separators=(",", ":"),
534
+ ).encode("utf-8")
535
+ if len(encoded) > MAX_A2A_MESSAGE_BYTES:
536
+ raise ValueError("A2A Message canonical JSON exceeds 1 MiB")
537
+ return message
538
+
539
+ @staticmethod
540
+ def _validate_prepared_target(
541
+ agent: DiscoveredAgent,
542
+ prepared: PreparedA2AOperation,
543
+ ) -> None:
544
+ A2ASpaceClient._validate_prepared_ids(prepared)
545
+ if prepared.target.agent_id != agent.agent_id:
546
+ raise RuntimeError("PrepareA2ACall returned a different target Agent")
547
+ if prepared.target.version_id != agent.version_id:
548
+ raise RuntimeError("PrepareA2ACall returned a different target version")
549
+ if agent.card_sha256 and prepared.target.card_sha256 != agent.card_sha256:
550
+ raise RuntimeError("PrepareA2ACall returned a different AgentCard hash")
551
+
552
+ @staticmethod
553
+ def _validate_prepared_ids(prepared: PreparedA2AOperation) -> None:
554
+ require_a2a_resource_id(
555
+ prepared.platform_task_id,
556
+ "a2a-task-",
557
+ field_name="PreparedA2AOperation.platform_task_id",
558
+ )
559
+ require_a2a_resource_id(
560
+ prepared.target.agent_id,
561
+ "a2a-agent-",
562
+ field_name="PreparedA2AOperation.target.agent_id",
563
+ )
564
+ require_a2a_resource_id(
565
+ prepared.target.version_id,
566
+ "a2a-version-",
567
+ field_name="PreparedA2AOperation.target.version_id",
568
+ )
569
+
570
+ @staticmethod
571
+ def _require_remote_task(prepared: PreparedA2AOperation):
572
+ remote_task = prepared.remote_task
573
+ if remote_task is None or not remote_task.remote_task_id:
574
+ raise RuntimeError("A2A_REMOTE_TASK_NOT_BOUND")
575
+ return remote_task
576
+
577
+ @staticmethod
578
+ def _operation_instance_id(prepared: PreparedA2AOperation) -> str:
579
+ return hashlib.sha256(prepared.call_permit.encode("utf-8")).hexdigest()
580
+
581
+ @staticmethod
582
+ def _validate_remote_task_observation(
583
+ expected_task_id: str,
584
+ expected_context_id: str | None,
585
+ item: Any,
586
+ ) -> None:
587
+ task = _present_message_field(item, "task")
588
+ if task is None and hasattr(item, "status") and hasattr(item, "id"):
589
+ task = item
590
+ status_update = _present_message_field(item, "status_update")
591
+ artifact_update = _present_message_field(item, "artifact_update")
592
+ message = _present_message_field(item, "message")
593
+ candidate = task or status_update or artifact_update or message
594
+ if candidate is None:
595
+ return
596
+ observed_task_id = str(
597
+ getattr(candidate, "id", "") or getattr(candidate, "task_id", "") or ""
598
+ )
599
+ observed_context_id = str(getattr(candidate, "context_id", "") or "") or None
600
+ if observed_task_id and observed_task_id != expected_task_id:
601
+ raise RuntimeError("A2A_REMOTE_BINDING_CONFLICT")
602
+ if observed_context_id != expected_context_id:
603
+ raise RuntimeError("A2A_REMOTE_BINDING_CONFLICT")
604
+
605
+ def _agent_from_prepared(self, prepared: PreparedA2AOperation) -> DiscoveredAgent:
606
+ cached = self._agents_by_id.get(prepared.target.agent_id)
607
+ if cached is not None and cached.version_id == prepared.target.version_id:
608
+ return cached
609
+ card = self._route_only_card(prepared.target.agent_id, prepared.target.version_id)
610
+ return DiscoveredAgent(
611
+ agent_id=prepared.target.agent_id,
612
+ version_id=prepared.target.version_id,
613
+ source="hosted" if prepared.route.kind == "hosted_gateway" else "external",
614
+ agent_card=card,
615
+ card_sha256=prepared.target.card_sha256,
616
+ route_kind=prepared.route.kind,
617
+ )
618
+
619
+ def _route_only_card(self, name: str, version: str) -> AgentCard:
620
+ return ParseDict(
621
+ {
622
+ "name": name,
623
+ "description": "AgentEngine prepared A2A route",
624
+ "version": version,
625
+ "supportedInterfaces": [],
626
+ "capabilities": {},
627
+ "defaultInputModes": ["text/plain"],
628
+ "defaultOutputModes": ["text/plain"],
629
+ "skills": [],
630
+ },
631
+ AgentCard(),
632
+ )
633
+
634
+ @asynccontextmanager
635
+ async def _operation_client(
636
+ self,
637
+ agent: DiscoveredAgent,
638
+ prepared: PreparedA2AOperation,
639
+ ) -> AsyncIterator[tuple[Any, ClientCallContext]]:
640
+ # Product bootstrap starts the shared dispatcher during lifespan startup.
641
+ # Standalone/from_env clients own their dispatcher and must start it here.
642
+ await self._event_dispatcher.start()
643
+ injection = CredentialInjection()
644
+ headers: dict[str, str]
645
+ async with AsyncExitStack() as exit_stack:
646
+ if prepared.route.kind == "hosted_gateway":
647
+ token = self._backend.gateway_token()
648
+ headers = {
649
+ "X-AgentEngine-A2A-Permit": prepared.call_permit,
650
+ }
651
+ if token:
652
+ headers["Authorization"] = f"Bearer {token}"
653
+ http = self._httpx_client
654
+ else:
655
+ if prepared.route.kind == "external_public" and not self._egress_enabled:
656
+ raise PermissionError(ERR_PUBLIC_EGRESS_DISABLED)
657
+ if self._external_transport is None:
658
+ raise RuntimeError(
659
+ "A2A_EGRESS_TRANSPORT_REQUIRED: external calls require a Runtime network "
660
+ "guard transport"
661
+ )
662
+ lease = await exit_stack.enter_async_context(
663
+ self._external_transport.open_for_route(
664
+ prepared.route.interface,
665
+ route_kind=prepared.route.kind,
666
+ )
667
+ )
668
+ http = lease.httpx_client
669
+ injection = await self._backend.resolve_credential(
670
+ platform_task_id=prepared.platform_task_id,
671
+ credential_handle=prepared.credential_handle,
672
+ call_permit=prepared.call_permit,
673
+ )
674
+ headers = dict(injection.headers)
675
+ if injection.cookies:
676
+ if any(name.lower() == "cookie" for name in headers):
677
+ raise RuntimeError(
678
+ "A2A_CREDENTIAL_INJECTION_CONFLICT: Cookie header and cookie injection "
679
+ "cannot both be present"
680
+ )
681
+ headers["Cookie"] = self._cookie_header(injection.cookies)
682
+ route = prepared.route.interface
683
+ if injection.query:
684
+ route = A2ARouteInterface(
685
+ url=self._url_with_query(route.url, injection.query),
686
+ protocol_binding=route.protocol_binding,
687
+ protocol_version=route.protocol_version,
688
+ )
689
+ route_card = self._card_for_route(agent.agent_card, route)
690
+ owned_http = None
691
+ if http is None:
692
+ # 外部调用方需自行传入已配置 verify 的 httpx_client。
693
+ owned_http = httpx.AsyncClient(trust_env=False)
694
+ http = owned_http
695
+ client = await create_client(
696
+ agent=route_card,
697
+ client_config=ClientConfig(httpx_client=http, streaming=True),
698
+ )
699
+ try:
700
+ yield client, ClientCallContext(service_parameters=headers or None)
701
+ finally:
702
+ if owned_http is not None:
703
+ await client.close()
704
+ await owned_http.aclose()
705
+
706
+ @staticmethod
707
+ def _url_with_query(url: str, query: dict[str, str]) -> str:
708
+ parsed = urlsplit(url)
709
+ values = parse_qsl(parsed.query, keep_blank_values=True)
710
+ existing = {name for name, _ in values}
711
+ collision = existing.intersection(query)
712
+ if collision:
713
+ raise RuntimeError(
714
+ "A2A_CREDENTIAL_INJECTION_CONFLICT: credential query collides with route query: "
715
+ f"{sorted(collision)}"
716
+ )
717
+ values.extend(query.items())
718
+ return urlunsplit(
719
+ (parsed.scheme, parsed.netloc, parsed.path, urlencode(values), parsed.fragment)
720
+ )
721
+
722
+ @staticmethod
723
+ def _cookie_header(cookies: dict[str, str]) -> str:
724
+ jar = SimpleCookie()
725
+ try:
726
+ for name, value in cookies.items():
727
+ jar[name] = value
728
+ except CookieError as exc:
729
+ raise RuntimeError(
730
+ "A2A_CREDENTIAL_INJECTION_CONFLICT: invalid credential cookie"
731
+ ) from exc
732
+ return jar.output(header="", sep="; ").strip()
733
+
734
+ @staticmethod
735
+ def _card_for_route(card: AgentCard, route: A2ARouteInterface) -> AgentCard:
736
+ payload = _canonical_proto(card)
737
+ payload["supportedInterfaces"] = [
738
+ {
739
+ "url": route.url,
740
+ "protocolBinding": route.protocol_binding,
741
+ "protocolVersion": route.protocol_version,
742
+ }
743
+ ]
744
+ return ParseDict(payload, AgentCard())
745
+
746
+ async def _bind_task(self, platform_task_id: str, remote_task: Any) -> None:
747
+ await self._backend.bind_remote_task(
748
+ platform_task_id=platform_task_id,
749
+ remote_task_id=str(remote_task.id),
750
+ remote_context_id=str(remote_task.context_id or "") or None,
751
+ observed_at=_utc_now(),
752
+ )
753
+
754
+ async def _project_stream_item(
755
+ self,
756
+ platform_task_id: str,
757
+ item: Any,
758
+ agent: DiscoveredAgent,
759
+ *,
760
+ wire_position: int,
761
+ operation_instance_id: str,
762
+ ) -> list[RuntimeEvent]:
763
+ runtime_events = self._stream_item_to_events(
764
+ item,
765
+ agent,
766
+ wire_position=wire_position,
767
+ invocation_id=platform_task_id,
768
+ )
769
+ platform_events = self._platform_events(
770
+ item,
771
+ platform_task_id,
772
+ operation_instance_id=operation_instance_id,
773
+ wire_position=wire_position,
774
+ )
775
+ if platform_events:
776
+ await self._event_dispatcher.enqueue(
777
+ platform_task_id=platform_task_id,
778
+ events=platform_events,
779
+ )
780
+ return await self._persist_events(runtime_events)
781
+
782
+ def _platform_events(
783
+ self,
784
+ item: Any,
785
+ platform_task_id: str,
786
+ *,
787
+ operation_instance_id: str,
788
+ wire_position: int,
789
+ ) -> list[dict[str, Any]]:
790
+ events: list[dict[str, Any]] = []
791
+
792
+ def append_event(
793
+ kind: str,
794
+ payload: dict[str, Any],
795
+ *,
796
+ status: str | None = None,
797
+ occurred_at: str | None = None,
798
+ ) -> None:
799
+ events.append(
800
+ self._platform_event(
801
+ kind,
802
+ payload,
803
+ platform_task_id,
804
+ operation_instance_id=operation_instance_id,
805
+ wire_position=wire_position,
806
+ event_ordinal=len(events),
807
+ status=status,
808
+ occurred_at=occurred_at,
809
+ )
810
+ )
811
+
812
+ task = _present_message_field(item, "task")
813
+ if task is None and hasattr(item, "status") and hasattr(item, "id"):
814
+ task = item
815
+ status_update = _present_message_field(item, "status_update")
816
+ artifact_update = _present_message_field(item, "artifact_update")
817
+ message = _present_message_field(item, "message")
818
+ if task is not None and getattr(task, "status", None) is not None:
819
+ payload = _canonical_proto(task.status)
820
+ state_name = TaskState.Name(task.status.state)
821
+ append_event(
822
+ "status",
823
+ payload,
824
+ status=state_name.removeprefix("TASK_STATE_").lower(),
825
+ occurred_at=str(payload.get("timestamp") or _utc_now()),
826
+ )
827
+ for artifact in getattr(task, "artifacts", None) or []:
828
+ append_event(
829
+ "artifact",
830
+ {
831
+ "Artifact": _canonical_proto(artifact),
832
+ "Append": False,
833
+ "LastChunk": True,
834
+ },
835
+ )
836
+ if status_update is not None and getattr(status_update, "status", None) is not None:
837
+ payload = _canonical_proto(status_update.status)
838
+ state_name = TaskState.Name(status_update.status.state)
839
+ append_event(
840
+ "status",
841
+ payload,
842
+ status=state_name.removeprefix("TASK_STATE_").lower(),
843
+ occurred_at=str(payload.get("timestamp") or _utc_now()),
844
+ )
845
+ if artifact_update is not None and getattr(artifact_update, "artifact", None) is not None:
846
+ append_event(
847
+ "artifact",
848
+ {
849
+ "Artifact": _canonical_proto(artifact_update.artifact),
850
+ "Append": bool(getattr(artifact_update, "append", False)),
851
+ "LastChunk": bool(getattr(artifact_update, "last_chunk", False)),
852
+ },
853
+ )
854
+ if message is not None:
855
+ payload = _canonical_proto(message)
856
+ append_event("message", payload)
857
+ append_event(
858
+ "status",
859
+ {"state": "TASK_STATE_COMPLETED", "message": payload},
860
+ status="completed",
861
+ )
862
+ return events
863
+
864
+ @staticmethod
865
+ def _platform_event(
866
+ kind: str,
867
+ payload: dict[str, Any],
868
+ platform_task_id: str,
869
+ *,
870
+ operation_instance_id: str,
871
+ wire_position: int,
872
+ event_ordinal: int,
873
+ status: str | None = None,
874
+ occurred_at: str | None = None,
875
+ ) -> dict[str, Any]:
876
+ source_id = hashlib.sha256(
877
+ (
878
+ f"{platform_task_id}:{operation_instance_id}:{wire_position}:{event_ordinal}:{kind}"
879
+ ).encode("utf-8")
880
+ ).hexdigest()
881
+ event: dict[str, Any] = {
882
+ "SourceEventId": source_id,
883
+ "EventKind": kind,
884
+ "Payload": payload,
885
+ "OccurredAt": occurred_at or _utc_now(),
886
+ }
887
+ if status:
888
+ event["Status"] = status
889
+ return event
890
+
891
+ async def flush_pending_events(self) -> int:
892
+ """Deliver all currently queued platform event batches or raise on failure."""
893
+
894
+ return await self._event_dispatcher.drain(raise_on_error=True)
895
+
896
+ def _next_seq(self) -> int:
897
+ self._seq += 1
898
+ return self._seq
899
+
900
+ def _event_ctx(
901
+ self,
902
+ agent: DiscoveredAgent,
903
+ invocation_id: str,
904
+ *,
905
+ event_id: str | None = None,
906
+ ) -> dict[str, Any]:
907
+ return {
908
+ "agent_id": agent.agent_id,
909
+ "user_id": "a2a_space",
910
+ "session_id": self._space_id,
911
+ "invocation_id": invocation_id,
912
+ "seq_id": self._next_seq(),
913
+ "event_id": event_id,
914
+ }
915
+
916
+ def task_to_event(self, task: Any, agent: DiscoveredAgent) -> RuntimeEvent:
917
+ return self._event_adapter.task_status_to_event(
918
+ task.status, **self._event_ctx(agent, invocation_id=str(task.id))
919
+ )
920
+
921
+ def _stream_item_to_events(
922
+ self,
923
+ item: Any,
924
+ agent: DiscoveredAgent,
925
+ *,
926
+ wire_position: int = 0,
927
+ invocation_id: str | None = None,
928
+ ) -> list[RuntimeEvent]:
929
+ events: list[RuntimeEvent] = []
930
+ task = _present_message_field(item, "task")
931
+ if task is None and hasattr(item, "status") and hasattr(item, "id"):
932
+ task = item
933
+ status_update = _present_message_field(item, "status_update")
934
+ artifact_update = _present_message_field(item, "artifact_update")
935
+ message = _present_message_field(item, "message")
936
+ resolved_invocation_id = invocation_id or str(
937
+ getattr(item, "task_id", None)
938
+ or getattr(task, "id", "")
939
+ or getattr(status_update, "task_id", "")
940
+ or getattr(artifact_update, "task_id", "")
941
+ or getattr(message, "task_id", "")
942
+ or ""
943
+ )
944
+
945
+ def ctx(kind: str, value: Any) -> dict[str, Any]:
946
+ metadata = getattr(value, "metadata", None)
947
+ native_event_id = ""
948
+ if metadata is not None:
949
+ if isinstance(metadata, Mapping):
950
+ metadata_dict = dict(metadata)
951
+ else:
952
+ try:
953
+ metadata_dict = MessageToDict(metadata, preserving_proto_field_name=True)
954
+ except (AttributeError, TypeError, ValueError):
955
+ metadata_dict = {}
956
+ native_event_id = str(
957
+ metadata_dict.get("event_id") or metadata_dict.get("ksadk_event_id") or ""
958
+ )
959
+ message_id = str(getattr(value, "message_id", "") or "")
960
+ artifact = getattr(value, "artifact", None)
961
+ artifact_id = str(
962
+ getattr(value, "artifact_id", "") or getattr(artifact, "artifact_id", "") or ""
963
+ )
964
+ source_id = native_event_id or message_id or artifact_id
965
+ event_id = uuid.uuid5(
966
+ uuid.NAMESPACE_URL,
967
+ f"ksadk:a2a:{resolved_invocation_id}:{wire_position}:{kind}:{source_id}",
968
+ ).hex
969
+ return self._event_ctx(agent, invocation_id=resolved_invocation_id, event_id=event_id)
970
+
971
+ if task is not None and getattr(task, "status", None) is not None:
972
+ task_status_message = _present_message_field(task.status, "message")
973
+ task_status_text = A2AEventAdapter._parts_text(
974
+ getattr(task_status_message, "parts", None)
975
+ )
976
+ task_is_terminal = task.status.state in {
977
+ TaskState.TASK_STATE_COMPLETED,
978
+ TaskState.TASK_STATE_FAILED,
979
+ TaskState.TASK_STATE_CANCELED,
980
+ TaskState.TASK_STATE_REJECTED,
981
+ }
982
+ if not task_is_terminal:
983
+ events.append(
984
+ self._event_adapter.task_status_to_event(
985
+ task.status,
986
+ **ctx("task", task),
987
+ )
988
+ )
989
+ if task_status_text:
990
+ events.append(
991
+ self._event_adapter.message_to_event(
992
+ task_status_text,
993
+ final=task_is_terminal,
994
+ **ctx("task-status-message", task_status_message),
995
+ )
996
+ )
997
+ if task_is_terminal:
998
+ events.append(
999
+ self._event_adapter.task_status_to_event(
1000
+ task.status,
1001
+ **ctx("task", task),
1002
+ )
1003
+ )
1004
+ if status_update is not None and getattr(status_update, "status", None) is not None:
1005
+ status_message = _present_message_field(status_update.status, "message")
1006
+ text = A2AEventAdapter._parts_text(getattr(status_message, "parts", None))
1007
+ terminal_states = {
1008
+ TaskState.TASK_STATE_COMPLETED,
1009
+ TaskState.TASK_STATE_FAILED,
1010
+ TaskState.TASK_STATE_CANCELED,
1011
+ TaskState.TASK_STATE_REJECTED,
1012
+ }
1013
+ is_terminal = status_update.status.state in terminal_states
1014
+ if not is_terminal:
1015
+ events.append(
1016
+ self._event_adapter.task_status_to_event(
1017
+ status_update.status, **ctx("status", status_update)
1018
+ )
1019
+ )
1020
+ if text:
1021
+ events.append(
1022
+ self._event_adapter.message_to_event(
1023
+ text,
1024
+ final=is_terminal,
1025
+ **ctx("status-message", status_message),
1026
+ )
1027
+ )
1028
+ if is_terminal:
1029
+ events.append(
1030
+ self._event_adapter.task_status_to_event(
1031
+ status_update.status, **ctx("status", status_update)
1032
+ )
1033
+ )
1034
+ if artifact_update is not None and getattr(artifact_update, "artifact", None) is not None:
1035
+ artifact = artifact_update.artifact
1036
+ events.append(
1037
+ self._event_adapter.artifact_to_event(artifact, **ctx("artifact", artifact_update))
1038
+ )
1039
+ artifact_text = A2AEventAdapter._parts_text(getattr(artifact, "parts", None))
1040
+ if artifact_text and str(getattr(artifact, "name", "") or "") == "response":
1041
+ events.append(
1042
+ self._event_adapter.message_to_event(
1043
+ artifact_text,
1044
+ final=bool(getattr(artifact_update, "last_chunk", False)),
1045
+ **ctx("artifact-text", artifact_update),
1046
+ )
1047
+ )
1048
+ if message is not None:
1049
+ text = A2AEventAdapter._parts_text(getattr(message, "parts", None))
1050
+ if text:
1051
+ events.append(
1052
+ self._event_adapter.message_to_event(
1053
+ text, final=True, **ctx("message", message)
1054
+ )
1055
+ )
1056
+ return events
1057
+
1058
+ async def _persist_events(self, events: list[RuntimeEvent]) -> list[RuntimeEvent]:
1059
+ existing_ids = set(self._persisted_wire_events)
1060
+ if self._event_sink is not None:
1061
+ list_events = getattr(self._event_sink, "list", None)
1062
+ if callable(list_events) and events:
1063
+ persisted_before = await list_events(events[0].session_id)
1064
+ existing_ids.update(event.event_id for event in persisted_before)
1065
+ fresh = [event for event in events if event.event_id not in existing_ids]
1066
+ if not fresh:
1067
+ return []
1068
+ if self._event_sink is not None:
1069
+ append = getattr(self._event_sink, "append", None)
1070
+ if append is None:
1071
+ raise TypeError("event_sink must provide async append(events)")
1072
+ persisted = await append(fresh)
1073
+ if persisted is not None:
1074
+ fresh = list(persisted)
1075
+ self._persisted_wire_events.update(event.event_id for event in fresh)
1076
+ return fresh
1077
+
1078
+ async def subscribe_events(self, task_id: str):
1079
+ require_a2a_resource_id(task_id, "a2a-task-", field_name="task_id")
1080
+ prepared = await self._backend.prepare_task_operation(
1081
+ platform_task_id=task_id,
1082
+ operation="subscribe_to_task",
1083
+ )
1084
+ self._validate_prepared_ids(prepared)
1085
+ agent = self._agent_from_prepared(prepared)
1086
+ async for _, persisted in self._iter_subscription(prepared, agent):
1087
+ for event in persisted:
1088
+ yield event
1089
+
1090
+ async def subscribe_persisted_events(
1091
+ self,
1092
+ *,
1093
+ after_seq_id: int = 0,
1094
+ timeout: float = 1.0,
1095
+ ) -> AsyncIterator[RuntimeEvent]:
1096
+ subscribe = getattr(self._event_sink, "subscribe_session", None)
1097
+ if subscribe is None:
1098
+ raise RuntimeError("event_sink does not support subscribe_session cursor replay")
1099
+ async for event in subscribe(
1100
+ self._space_id,
1101
+ after_seq_id=after_seq_id,
1102
+ timeout=timeout,
1103
+ ):
1104
+ yield event
1105
+
1106
+ async def _record_agent_for_task(self, task_id: str, agent: DiscoveredAgent) -> None:
1107
+ set_task_agent = getattr(self._event_sink, "set_task_agent", None)
1108
+ if callable(set_task_agent):
1109
+ await set_task_agent(self._space_id, task_id, agent.agent_id)
1110
+
1111
+
1112
+ __all__ = [
1113
+ "A2AExternalTransport",
1114
+ "A2APlatformTask",
1115
+ "A2ASpaceClient",
1116
+ "DiscoveredAgent",
1117
+ "ENV_A2A_ENABLE_PUBLIC_EGRESS",
1118
+ "ENV_A2A_SPACE_ID",
1119
+ "ENV_A2A_SPACE_IDS",
1120
+ "ERR_PUBLIC_EGRESS_DISABLED",
1121
+ "SpaceAgentPage",
1122
+ ]