openhands-agent-server 1.51.0__tar.gz → 1.52.0__tar.gz

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 (102) hide show
  1. {openhands_agent_server-1.51.0 → openhands_agent_server-1.52.0}/PKG-INFO +3 -3
  2. {openhands_agent_server-1.51.0 → openhands_agent_server-1.52.0}/openhands/agent_server/api.py +20 -27
  3. {openhands_agent_server-1.51.0 → openhands_agent_server-1.52.0}/openhands/agent_server/bash_router.py +23 -0
  4. {openhands_agent_server-1.51.0 → openhands_agent_server-1.52.0}/openhands/agent_server/bash_service.py +55 -0
  5. {openhands_agent_server-1.51.0 → openhands_agent_server-1.52.0}/openhands/agent_server/conversation_router.py +74 -0
  6. {openhands_agent_server-1.51.0 → openhands_agent_server-1.52.0}/openhands/agent_server/conversation_service.py +221 -184
  7. {openhands_agent_server-1.51.0 → openhands_agent_server-1.52.0}/openhands/agent_server/event_service.py +44 -11
  8. {openhands_agent_server-1.51.0 → openhands_agent_server-1.52.0}/openhands/agent_server/openai/router.py +11 -0
  9. {openhands_agent_server-1.51.0 → openhands_agent_server-1.52.0}/openhands/agent_server/server_details_router.py +4 -0
  10. {openhands_agent_server-1.51.0 → openhands_agent_server-1.52.0}/openhands_agent_server.egg-info/PKG-INFO +3 -3
  11. {openhands_agent_server-1.51.0 → openhands_agent_server-1.52.0}/openhands_agent_server.egg-info/requires.txt +2 -2
  12. {openhands_agent_server-1.51.0 → openhands_agent_server-1.52.0}/pyproject.toml +5 -5
  13. {openhands_agent_server-1.51.0 → openhands_agent_server-1.52.0}/openhands/agent_server/__init__.py +0 -0
  14. {openhands_agent_server-1.51.0 → openhands_agent_server-1.52.0}/openhands/agent_server/__main__.py +0 -0
  15. {openhands_agent_server-1.51.0 → openhands_agent_server-1.52.0}/openhands/agent_server/_secret_redaction.py +0 -0
  16. {openhands_agent_server-1.51.0 → openhands_agent_server-1.52.0}/openhands/agent_server/_secrets_exposure.py +0 -0
  17. {openhands_agent_server-1.51.0 → openhands_agent_server-1.52.0}/openhands/agent_server/agent_profiles_router.py +0 -0
  18. {openhands_agent_server-1.51.0 → openhands_agent_server-1.52.0}/openhands/agent_server/auth_router.py +0 -0
  19. {openhands_agent_server-1.51.0 → openhands_agent_server-1.52.0}/openhands/agent_server/canvas_extensions/__init__.py +0 -0
  20. {openhands_agent_server-1.51.0 → openhands_agent_server-1.52.0}/openhands/agent_server/canvas_extensions/backend.py +0 -0
  21. {openhands_agent_server-1.51.0 → openhands_agent_server-1.52.0}/openhands/agent_server/canvas_extensions/bridge.py +0 -0
  22. {openhands_agent_server-1.51.0 → openhands_agent_server-1.52.0}/openhands/agent_server/canvas_extensions/installed.py +0 -0
  23. {openhands_agent_server-1.51.0 → openhands_agent_server-1.52.0}/openhands/agent_server/canvas_extensions/manifest.py +0 -0
  24. {openhands_agent_server-1.51.0 → openhands_agent_server-1.52.0}/openhands/agent_server/canvas_extensions_bridge_router.py +0 -0
  25. {openhands_agent_server-1.51.0 → openhands_agent_server-1.52.0}/openhands/agent_server/canvas_extensions_router.py +0 -0
  26. {openhands_agent_server-1.51.0 → openhands_agent_server-1.52.0}/openhands/agent_server/config.py +0 -0
  27. {openhands_agent_server-1.51.0 → openhands_agent_server-1.52.0}/openhands/agent_server/conversation_lease.py +0 -0
  28. {openhands_agent_server-1.51.0 → openhands_agent_server-1.52.0}/openhands/agent_server/conversation_registry.py +0 -0
  29. {openhands_agent_server-1.51.0 → openhands_agent_server-1.52.0}/openhands/agent_server/credential_binding.py +0 -0
  30. {openhands_agent_server-1.51.0 → openhands_agent_server-1.52.0}/openhands/agent_server/dependencies.py +0 -0
  31. {openhands_agent_server-1.51.0 → openhands_agent_server-1.52.0}/openhands/agent_server/docker/Dockerfile +0 -0
  32. {openhands_agent_server-1.51.0 → openhands_agent_server-1.52.0}/openhands/agent_server/docker/build.py +0 -0
  33. {openhands_agent_server-1.51.0 → openhands_agent_server-1.52.0}/openhands/agent_server/docker_runtime/__init__.py +0 -0
  34. {openhands_agent_server-1.51.0 → openhands_agent_server-1.52.0}/openhands/agent_server/docker_runtime/mediation.py +0 -0
  35. {openhands_agent_server-1.51.0 → openhands_agent_server-1.52.0}/openhands/agent_server/docker_runtime/provisioning.py +0 -0
  36. {openhands_agent_server-1.51.0 → openhands_agent_server-1.52.0}/openhands/agent_server/docker_runtime/proxy.py +0 -0
  37. {openhands_agent_server-1.51.0 → openhands_agent_server-1.52.0}/openhands/agent_server/docker_runtime/registry.py +0 -0
  38. {openhands_agent_server-1.51.0 → openhands_agent_server-1.52.0}/openhands/agent_server/docker_runtime/routers.py +0 -0
  39. {openhands_agent_server-1.51.0 → openhands_agent_server-1.52.0}/openhands/agent_server/env_parser.py +0 -0
  40. {openhands_agent_server-1.51.0 → openhands_agent_server-1.52.0}/openhands/agent_server/event_router.py +0 -0
  41. {openhands_agent_server-1.51.0 → openhands_agent_server-1.52.0}/openhands/agent_server/file_router.py +0 -0
  42. {openhands_agent_server-1.51.0 → openhands_agent_server-1.52.0}/openhands/agent_server/git_provider_service.py +0 -0
  43. {openhands_agent_server-1.51.0 → openhands_agent_server-1.52.0}/openhands/agent_server/git_router.py +0 -0
  44. {openhands_agent_server-1.51.0 → openhands_agent_server-1.52.0}/openhands/agent_server/hooks_router.py +0 -0
  45. {openhands_agent_server-1.51.0 → openhands_agent_server-1.52.0}/openhands/agent_server/hooks_service.py +0 -0
  46. {openhands_agent_server-1.51.0 → openhands_agent_server-1.52.0}/openhands/agent_server/init_router.py +0 -0
  47. {openhands_agent_server-1.51.0 → openhands_agent_server-1.52.0}/openhands/agent_server/launch.py +0 -0
  48. {openhands_agent_server-1.51.0 → openhands_agent_server-1.52.0}/openhands/agent_server/llm_router.py +0 -0
  49. {openhands_agent_server-1.51.0 → openhands_agent_server-1.52.0}/openhands/agent_server/local_secret_resolver.py +0 -0
  50. {openhands_agent_server-1.51.0 → openhands_agent_server-1.52.0}/openhands/agent_server/logging_config.py +0 -0
  51. {openhands_agent_server-1.51.0 → openhands_agent_server-1.52.0}/openhands/agent_server/managed_llm_key.py +0 -0
  52. {openhands_agent_server-1.51.0 → openhands_agent_server-1.52.0}/openhands/agent_server/mcp_oauth_store.py +0 -0
  53. {openhands_agent_server-1.51.0 → openhands_agent_server-1.52.0}/openhands/agent_server/mcp_router.py +0 -0
  54. {openhands_agent_server-1.51.0 → openhands_agent_server-1.52.0}/openhands/agent_server/meta_profiles_router.py +0 -0
  55. {openhands_agent_server-1.51.0 → openhands_agent_server-1.52.0}/openhands/agent_server/middleware.py +0 -0
  56. {openhands_agent_server-1.51.0 → openhands_agent_server-1.52.0}/openhands/agent_server/models.py +0 -0
  57. {openhands_agent_server-1.51.0 → openhands_agent_server-1.52.0}/openhands/agent_server/openai/__init__.py +0 -0
  58. {openhands_agent_server-1.51.0 → openhands_agent_server-1.52.0}/openhands/agent_server/openai/models.py +0 -0
  59. {openhands_agent_server-1.51.0 → openhands_agent_server-1.52.0}/openhands/agent_server/openai/service.py +0 -0
  60. {openhands_agent_server-1.51.0 → openhands_agent_server-1.52.0}/openhands/agent_server/openapi.py +0 -0
  61. {openhands_agent_server-1.51.0 → openhands_agent_server-1.52.0}/openhands/agent_server/persistence/__init__.py +0 -0
  62. {openhands_agent_server-1.51.0 → openhands_agent_server-1.52.0}/openhands/agent_server/persistence/models.py +0 -0
  63. {openhands_agent_server-1.51.0 → openhands_agent_server-1.52.0}/openhands/agent_server/persistence/store.py +0 -0
  64. {openhands_agent_server-1.51.0 → openhands_agent_server-1.52.0}/openhands/agent_server/plugins_router.py +0 -0
  65. {openhands_agent_server-1.51.0 → openhands_agent_server-1.52.0}/openhands/agent_server/plugins_service.py +0 -0
  66. {openhands_agent_server-1.51.0 → openhands_agent_server-1.52.0}/openhands/agent_server/profiles_router.py +0 -0
  67. {openhands_agent_server-1.51.0 → openhands_agent_server-1.52.0}/openhands/agent_server/provider_connections_router.py +0 -0
  68. {openhands_agent_server-1.51.0 → openhands_agent_server-1.52.0}/openhands/agent_server/pub_sub.py +0 -0
  69. {openhands_agent_server-1.51.0 → openhands_agent_server-1.52.0}/openhands/agent_server/py.typed +0 -0
  70. {openhands_agent_server-1.51.0 → openhands_agent_server-1.52.0}/openhands/agent_server/runtime_router.py +0 -0
  71. {openhands_agent_server-1.51.0 → openhands_agent_server-1.52.0}/openhands/agent_server/session_protocol.py +0 -0
  72. {openhands_agent_server-1.51.0 → openhands_agent_server-1.52.0}/openhands/agent_server/session_socket.py +0 -0
  73. {openhands_agent_server-1.51.0 → openhands_agent_server-1.52.0}/openhands/agent_server/settings_router.py +0 -0
  74. {openhands_agent_server-1.51.0 → openhands_agent_server-1.52.0}/openhands/agent_server/skills_router.py +0 -0
  75. {openhands_agent_server-1.51.0 → openhands_agent_server-1.52.0}/openhands/agent_server/skills_service.py +0 -0
  76. {openhands_agent_server-1.51.0 → openhands_agent_server-1.52.0}/openhands/agent_server/sockets.py +0 -0
  77. {openhands_agent_server-1.51.0 → openhands_agent_server-1.52.0}/openhands/agent_server/sub_agents_router.py +0 -0
  78. {openhands_agent_server-1.51.0 → openhands_agent_server-1.52.0}/openhands/agent_server/telemetry/__init__.py +0 -0
  79. {openhands_agent_server-1.51.0 → openhands_agent_server-1.52.0}/openhands/agent_server/telemetry/factory.py +0 -0
  80. {openhands_agent_server-1.51.0 → openhands_agent_server-1.52.0}/openhands/agent_server/telemetry/http_exporter.py +0 -0
  81. {openhands_agent_server-1.51.0 → openhands_agent_server-1.52.0}/openhands/agent_server/telemetry/models.py +0 -0
  82. {openhands_agent_server-1.51.0 → openhands_agent_server-1.52.0}/openhands/agent_server/telemetry/policy.py +0 -0
  83. {openhands_agent_server-1.51.0 → openhands_agent_server-1.52.0}/openhands/agent_server/telemetry/posthog_exporter.py +0 -0
  84. {openhands_agent_server-1.51.0 → openhands_agent_server-1.52.0}/openhands/agent_server/telemetry/sanitizer.py +0 -0
  85. {openhands_agent_server-1.51.0 → openhands_agent_server-1.52.0}/openhands/agent_server/telemetry/service.py +0 -0
  86. {openhands_agent_server-1.51.0 → openhands_agent_server-1.52.0}/openhands/agent_server/telemetry/sink.py +0 -0
  87. {openhands_agent_server-1.51.0 → openhands_agent_server-1.52.0}/openhands/agent_server/telemetry/subscriber.py +0 -0
  88. {openhands_agent_server-1.51.0 → openhands_agent_server-1.52.0}/openhands/agent_server/telemetry_types.py +0 -0
  89. {openhands_agent_server-1.51.0 → openhands_agent_server-1.52.0}/openhands/agent_server/tool_preload_service.py +0 -0
  90. {openhands_agent_server-1.51.0 → openhands_agent_server-1.52.0}/openhands/agent_server/tool_router.py +0 -0
  91. {openhands_agent_server-1.51.0 → openhands_agent_server-1.52.0}/openhands/agent_server/utils.py +0 -0
  92. {openhands_agent_server-1.51.0 → openhands_agent_server-1.52.0}/openhands/agent_server/vscode_extensions/openhands-settings/extension.js +0 -0
  93. {openhands_agent_server-1.51.0 → openhands_agent_server-1.52.0}/openhands/agent_server/vscode_extensions/openhands-settings/package.json +0 -0
  94. {openhands_agent_server-1.51.0 → openhands_agent_server-1.52.0}/openhands/agent_server/vscode_router.py +0 -0
  95. {openhands_agent_server-1.51.0 → openhands_agent_server-1.52.0}/openhands/agent_server/vscode_service.py +0 -0
  96. {openhands_agent_server-1.51.0 → openhands_agent_server-1.52.0}/openhands/agent_server/workspace_router.py +0 -0
  97. {openhands_agent_server-1.51.0 → openhands_agent_server-1.52.0}/openhands/agent_server/workspaces_router.py +0 -0
  98. {openhands_agent_server-1.51.0 → openhands_agent_server-1.52.0}/openhands_agent_server.egg-info/SOURCES.txt +0 -0
  99. {openhands_agent_server-1.51.0 → openhands_agent_server-1.52.0}/openhands_agent_server.egg-info/dependency_links.txt +0 -0
  100. {openhands_agent_server-1.51.0 → openhands_agent_server-1.52.0}/openhands_agent_server.egg-info/entry_points.txt +0 -0
  101. {openhands_agent_server-1.51.0 → openhands_agent_server-1.52.0}/openhands_agent_server.egg-info/top_level.txt +0 -0
  102. {openhands_agent_server-1.51.0 → openhands_agent_server-1.52.0}/setup.cfg +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: openhands-agent-server
3
- Version: 1.51.0
3
+ Version: 1.52.0
4
4
  Summary: OpenHands Agent Server - REST/WebSocket interface for OpenHands AI Agent
5
5
  Project-URL: Source, https://github.com/OpenHands/software-agent-sdk
6
6
  Project-URL: Homepage, https://github.com/OpenHands/software-agent-sdk
@@ -16,8 +16,8 @@ Requires-Dist: openhands-tools
16
16
  Requires-Dist: openai<3,>=2.33.0
17
17
  Requires-Dist: pydantic>=2.13.5
18
18
  Requires-Dist: sqlalchemy>=2
19
- Requires-Dist: uvicorn>=0.52.4
19
+ Requires-Dist: uvicorn>=0.54.0
20
20
  Requires-Dist: websockets>=12
21
21
  Requires-Dist: wsproto>=1.2.0
22
22
  Provides-Extra: posthog
23
- Requires-Dist: posthog<7,>=6; extra == "posthog"
23
+ Requires-Dist: posthog<8,>=7.60.0; extra == "posthog"
@@ -133,33 +133,26 @@ def _ensure_server_tmux_tmpdir() -> tuple[Path, bool]:
133
133
 
134
134
 
135
135
  def _cleanup_stale_tmux_sessions() -> None:
136
- """Clean up any stale tmux sessions on server startup.
137
-
138
- Tmux sessions live in a separate process that survives agent-server restarts.
139
- This function kills all existing sessions on the shared OpenHands tmux socket
140
- to prevent accumulation of orphaned sessions.
141
- """
142
- try:
143
- server = libtmux.Server(socket_name=TMUX_SOCKET_NAME)
144
- sessions = server.sessions
145
- if not sessions:
146
- logger.debug("No tmux sessions found on %s socket", TMUX_SOCKET_NAME)
147
- return
148
-
149
- logger.info("Cleaning up %d stale tmux session(s) on startup", len(sessions))
150
-
151
- for session in sessions:
152
- try:
153
- logger.debug("Killing tmux session: %s", session.name)
154
- session.kill()
155
- except Exception as e:
156
- logger.warning("Failed to kill tmux session %s: %s", session.name, e)
157
-
158
- logger.info("Tmux cleanup completed")
159
-
160
- except Exception as e:
161
- # Don't let tmux cleanup failures prevent server startup
162
- logger.warning("Failed to cleanup tmux sessions: %s", e)
136
+ """Clean up legacy and isolated terminal sockets on server startup."""
137
+ if os.name != "posix":
138
+ return
139
+ socket_dir = Path(os.environ.get("TMUX_TMPDIR", "/tmp")) / f"tmux-{os.getuid()}"
140
+ socket_names = [TMUX_SOCKET_NAME]
141
+ socket_names.extend(
142
+ path.name
143
+ for path in socket_dir.glob(f"{TMUX_SOCKET_NAME}-" + "[0-9a-f]" * 32)
144
+ if path.is_socket()
145
+ )
146
+ for socket_name in socket_names:
147
+ try:
148
+ server = libtmux.Server(socket_name=socket_name)
149
+ for session in server.sessions:
150
+ try:
151
+ session.kill()
152
+ except Exception as e:
153
+ logger.warning("Failed to kill tmux session %s: %s", session, e)
154
+ except Exception as e:
155
+ logger.warning("Failed to cleanup tmux socket %s: %s", socket_name, e)
163
156
 
164
157
 
165
158
  @asynccontextmanager
@@ -23,6 +23,7 @@ from openhands.agent_server.models import (
23
23
  BashEventSortOrder,
24
24
  BashOutput,
25
25
  ExecuteBashRequest,
26
+ Success,
26
27
  )
27
28
  from openhands.agent_server.server_details_router import update_last_execution_time
28
29
 
@@ -132,6 +133,28 @@ async def clear_all_bash_events(
132
133
  return {"cleared_count": count}
133
134
 
134
135
 
136
+ @bash_router.post(
137
+ "/bash_commands/{command_id}/stop",
138
+ responses={404: {"description": "Item not found"}},
139
+ )
140
+ async def stop_bash_command(
141
+ command_id: UUID,
142
+ bash_event_service: BashEventService = Depends(get_bash_event_service),
143
+ ) -> Success:
144
+ """Stop a running bash command by id without touching the others.
145
+
146
+ Idempotent: stopping an already-finished command succeeds, while an
147
+ unknown command id reports not-found so the caller can treat it as
148
+ an already-cancelled stop.
149
+ """
150
+ update_last_execution_time()
151
+ if await bash_event_service.stop_bash_command(command_id):
152
+ return Success()
153
+ if await bash_event_service.get_bash_event(command_id.hex) is not None:
154
+ return Success()
155
+ raise HTTPException(status.HTTP_404_NOT_FOUND)
156
+
157
+
135
158
  def _validate_cwd(request: ExecuteBashRequest, service: BashEventService) -> None:
136
159
  if service.default_cwd is not None and request.cwd is not None:
137
160
  if (
@@ -34,6 +34,16 @@ class BashEventService:
34
34
  default_cwd: str | None = None
35
35
  _tasks: set[asyncio.Task] = field(default_factory=set, init=False)
36
36
  _closed: bool = field(default=False, init=False)
37
+ # Processes of currently running commands, keyed by command id. A None
38
+ # value means the spawn is still pending: start_bash_command registers
39
+ # the id synchronously so a stop arriving before the subprocess exists
40
+ # is recorded instead of lost. Lets a stop-by-id operation signal one
41
+ # command without touching the others.
42
+ _processes: dict[UUID, asyncio.subprocess.Process | None] = field(
43
+ default_factory=dict, init=False
44
+ )
45
+ # Ids a stop was requested for while their spawn was still pending.
46
+ _stop_requests: set[UUID] = field(default_factory=set, init=False)
37
47
  _pub_sub: PubSub[BashEventBase] = field(
38
48
  default_factory=lambda: PubSub[BashEventBase](max_subscribers=50),
39
49
  init=False,
@@ -265,6 +275,9 @@ class BashEventService:
265
275
  self._save_event_to_file(command)
266
276
  await self._pub_sub(command)
267
277
 
278
+ # Register synchronously so a stop racing the spawn is recorded
279
+ # instead of lost; the task replaces None with the live process.
280
+ self._processes[command.id] = None
268
281
  # Execute the bash command in a background task
269
282
  task = asyncio.create_task(self._execute_bash_command(command))
270
283
  self._tasks.add(task)
@@ -286,6 +299,12 @@ class BashEventService:
286
299
  env=sanitized_env(),
287
300
  start_new_session=True,
288
301
  )
302
+ self._processes[command.id] = process
303
+ if command.id in self._stop_requests:
304
+ # A stop arrived before the spawn completed: apply it now
305
+ # instead of letting the command run to its timeout.
306
+ self._stop_requests.discard(command.id)
307
+ await self.stop_bash_command(command.id)
289
308
 
290
309
  # Track output order and buffers
291
310
  output_order = 0
@@ -413,6 +432,40 @@ class BashEventService:
413
432
 
414
433
  self._save_event_to_file(error_output)
415
434
  await self._pub_sub(error_output)
435
+ finally:
436
+ self._processes.pop(command.id, None)
437
+ self._stop_requests.discard(command.id)
438
+
439
+ async def stop_bash_command(self, command_id: UUID) -> bool:
440
+ """Stop a running command's process group by command id.
441
+
442
+ Reuses the timeout path's SIGTERM-then-SIGKILL escalation so
443
+ user-installed cleanup traps run. The command's own task observes
444
+ the exit and publishes the terminal output, so only signalling
445
+ is needed here.
446
+
447
+ A stop racing the spawn is recorded and applied as soon as the
448
+ subprocess exists. Returns True when the id is known (signalled
449
+ now, already finished, or recorded for a pending spawn).
450
+ Returns False only for unknown ids; the caller maps a
451
+ known-but-finished id to success and an unknown id to not-found.
452
+ """
453
+ if command_id not in self._processes:
454
+ return False
455
+ process = self._processes[command_id]
456
+ if process is None:
457
+ self._stop_requests.add(command_id)
458
+ return True
459
+ self._signal_process_group(process, signal.SIGTERM)
460
+ try:
461
+ await asyncio.wait_for(process.wait(), timeout=1.0)
462
+ except TimeoutError:
463
+ self._signal_process_group(process, signal.SIGKILL)
464
+ try:
465
+ await asyncio.wait_for(process.wait(), timeout=1.0)
466
+ except TimeoutError:
467
+ logger.error("Failed to stop process (command_id=%s)", command_id)
468
+ return True
416
469
 
417
470
  def delete_events_older_than(self, cutoff: datetime) -> int:
418
471
  """Delete bash event files with a recorded timestamp older than ``cutoff``.
@@ -525,6 +578,8 @@ class BashEventService:
525
578
  for task in tasks:
526
579
  task.cancel()
527
580
  await asyncio.gather(*tasks, return_exceptions=True)
581
+ self._processes.clear()
582
+ self._stop_requests.clear()
528
583
  await self._pub_sub.close()
529
584
 
530
585
  async def __aenter__(self):
@@ -1,5 +1,6 @@
1
1
  """Conversation router for OpenHands SDK."""
2
2
 
3
+ import json
3
4
  from typing import Annotated
4
5
  from uuid import UUID
5
6
 
@@ -7,12 +8,14 @@ from fastapi import (
7
8
  APIRouter,
8
9
  Body,
9
10
  Depends,
11
+ Header,
10
12
  HTTPException,
11
13
  Query,
12
14
  Request,
13
15
  Response,
14
16
  status,
15
17
  )
18
+ from pydantic import TypeAdapter, ValidationError
16
19
 
17
20
  from openhands.agent_server._secrets_exposure import (
18
21
  decrypt_incoming_llm_secrets,
@@ -50,6 +53,11 @@ from openhands.agent_server.models import (
50
53
  from openhands.agent_server.persistence import get_llm_profile_store
51
54
  from openhands.sdk import LLM
52
55
  from openhands.sdk.conversation.state import ConversationExecutionStatus
56
+ from openhands.sdk.conversation.types import (
57
+ ConversationObservabilityMetadata,
58
+ ConversationObservabilitySpanName,
59
+ ConversationObservabilityTags,
60
+ )
53
61
  from openhands.sdk.launch import AgentLaunchError, LaunchStoreError
54
62
  from openhands.sdk.marketplace.registry import (
55
63
  MarketplaceNotFoundError,
@@ -63,6 +71,53 @@ from openhands.sdk.tool.client_tool import ClientToolRegistrationError
63
71
 
64
72
  conversation_catalog_router = APIRouter(prefix="/conversations", tags=["Conversations"])
65
73
  conversation_router = APIRouter(prefix="/conversations", tags=["Conversations"])
74
+ _OBSERVABILITY_SPAN_NAME_ADAPTER = TypeAdapter(ConversationObservabilitySpanName)
75
+ _OBSERVABILITY_TAGS_ADAPTER = TypeAdapter(ConversationObservabilityTags)
76
+ _OBSERVABILITY_METADATA_ADAPTER = TypeAdapter(ConversationObservabilityMetadata)
77
+
78
+
79
+ def _request_with_observability_headers(
80
+ request: StartConversationRequest,
81
+ *,
82
+ span_name: str | None,
83
+ tags: str | None,
84
+ metadata: str | None,
85
+ parent_span_context: str | None,
86
+ ) -> StartConversationRequest:
87
+ updates: dict[str, object] = {}
88
+ try:
89
+ if span_name and "observability_span_name" not in request.model_fields_set:
90
+ updates["observability_span_name"] = (
91
+ _OBSERVABILITY_SPAN_NAME_ADAPTER.validate_python(span_name)
92
+ )
93
+ if tags and "observability_tags" not in request.model_fields_set:
94
+ tag_values = [tag.strip() for tag in tags.split(",") if tag.strip()]
95
+ updates["observability_tags"] = _OBSERVABILITY_TAGS_ADAPTER.validate_python(
96
+ tag_values
97
+ )
98
+ if metadata:
99
+ metadata_payload = json.loads(metadata)
100
+ header_metadata = _OBSERVABILITY_METADATA_ADAPTER.validate_python(
101
+ metadata_payload
102
+ )
103
+ updates["observability_metadata"] = {
104
+ **header_metadata,
105
+ **request.observability_metadata,
106
+ }
107
+ except json.JSONDecodeError as exc:
108
+ raise HTTPException(
109
+ status_code=422,
110
+ detail="X-OpenHands-Observability-Metadata must be a JSON object",
111
+ ) from exc
112
+ except ValidationError as exc:
113
+ raise HTTPException(
114
+ status_code=422,
115
+ detail=exc.errors(include_context=False),
116
+ ) from exc
117
+ if parent_span_context and not request.observability_parent_span_context:
118
+ updates["observability_parent_span_context"] = parent_span_context
119
+ return request.model_copy(update=updates) if updates else request
120
+
66
121
 
67
122
  # Examples
68
123
 
@@ -260,9 +315,28 @@ async def start_conversation(
260
315
  ],
261
316
  response: Response,
262
317
  include_skills: Annotated[bool, Query(title=INCLUDE_SKILLS_PARAM_TITLE)] = False,
318
+ x_openhands_observability_span_name: Annotated[
319
+ str | None, Header(alias="X-OpenHands-Observability-Span-Name")
320
+ ] = None,
321
+ x_openhands_observability_tags: Annotated[
322
+ str | None, Header(alias="X-OpenHands-Observability-Tags")
323
+ ] = None,
324
+ x_openhands_observability_metadata: Annotated[
325
+ str | None, Header(alias="X-OpenHands-Observability-Metadata")
326
+ ] = None,
327
+ x_openhands_observability_parent_span_context: Annotated[
328
+ str | None, Header(alias="X-OpenHands-Observability-Parent-Span-Context")
329
+ ] = None,
263
330
  conversation_service: ConversationService = Depends(get_conversation_service),
264
331
  ) -> ConversationInfo:
265
332
  """Start a conversation in the local environment."""
333
+ request = _request_with_observability_headers(
334
+ request,
335
+ span_name=x_openhands_observability_span_name,
336
+ tags=x_openhands_observability_tags,
337
+ metadata=x_openhands_observability_metadata,
338
+ parent_span_context=x_openhands_observability_parent_span_context,
339
+ )
266
340
  try:
267
341
  info, is_new = await conversation_service.start_conversation(request)
268
342
  except (ProfileNotFound, AgentLaunchError, LaunchStoreError) as e: