openhands-agent-server 1.51.0__tar.gz → 1.53.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.53.0}/PKG-INFO +3 -3
  2. {openhands_agent_server-1.51.0 → openhands_agent_server-1.53.0}/openhands/agent_server/api.py +20 -27
  3. {openhands_agent_server-1.51.0 → openhands_agent_server-1.53.0}/openhands/agent_server/bash_router.py +23 -0
  4. {openhands_agent_server-1.51.0 → openhands_agent_server-1.53.0}/openhands/agent_server/bash_service.py +55 -0
  5. {openhands_agent_server-1.51.0 → openhands_agent_server-1.53.0}/openhands/agent_server/canvas_extensions/installed.py +20 -0
  6. {openhands_agent_server-1.51.0 → openhands_agent_server-1.53.0}/openhands/agent_server/canvas_extensions/manifest.py +43 -4
  7. {openhands_agent_server-1.51.0 → openhands_agent_server-1.53.0}/openhands/agent_server/canvas_extensions_router.py +40 -0
  8. {openhands_agent_server-1.51.0 → openhands_agent_server-1.53.0}/openhands/agent_server/conversation_router.py +74 -0
  9. {openhands_agent_server-1.51.0 → openhands_agent_server-1.53.0}/openhands/agent_server/conversation_service.py +221 -184
  10. {openhands_agent_server-1.51.0 → openhands_agent_server-1.53.0}/openhands/agent_server/event_service.py +44 -11
  11. {openhands_agent_server-1.51.0 → openhands_agent_server-1.53.0}/openhands/agent_server/openai/router.py +11 -0
  12. {openhands_agent_server-1.51.0 → openhands_agent_server-1.53.0}/openhands/agent_server/server_details_router.py +4 -0
  13. {openhands_agent_server-1.51.0 → openhands_agent_server-1.53.0}/openhands_agent_server.egg-info/PKG-INFO +3 -3
  14. {openhands_agent_server-1.51.0 → openhands_agent_server-1.53.0}/openhands_agent_server.egg-info/requires.txt +2 -2
  15. {openhands_agent_server-1.51.0 → openhands_agent_server-1.53.0}/pyproject.toml +5 -5
  16. {openhands_agent_server-1.51.0 → openhands_agent_server-1.53.0}/openhands/agent_server/__init__.py +0 -0
  17. {openhands_agent_server-1.51.0 → openhands_agent_server-1.53.0}/openhands/agent_server/__main__.py +0 -0
  18. {openhands_agent_server-1.51.0 → openhands_agent_server-1.53.0}/openhands/agent_server/_secret_redaction.py +0 -0
  19. {openhands_agent_server-1.51.0 → openhands_agent_server-1.53.0}/openhands/agent_server/_secrets_exposure.py +0 -0
  20. {openhands_agent_server-1.51.0 → openhands_agent_server-1.53.0}/openhands/agent_server/agent_profiles_router.py +0 -0
  21. {openhands_agent_server-1.51.0 → openhands_agent_server-1.53.0}/openhands/agent_server/auth_router.py +0 -0
  22. {openhands_agent_server-1.51.0 → openhands_agent_server-1.53.0}/openhands/agent_server/canvas_extensions/__init__.py +0 -0
  23. {openhands_agent_server-1.51.0 → openhands_agent_server-1.53.0}/openhands/agent_server/canvas_extensions/backend.py +0 -0
  24. {openhands_agent_server-1.51.0 → openhands_agent_server-1.53.0}/openhands/agent_server/canvas_extensions/bridge.py +0 -0
  25. {openhands_agent_server-1.51.0 → openhands_agent_server-1.53.0}/openhands/agent_server/canvas_extensions_bridge_router.py +0 -0
  26. {openhands_agent_server-1.51.0 → openhands_agent_server-1.53.0}/openhands/agent_server/config.py +0 -0
  27. {openhands_agent_server-1.51.0 → openhands_agent_server-1.53.0}/openhands/agent_server/conversation_lease.py +0 -0
  28. {openhands_agent_server-1.51.0 → openhands_agent_server-1.53.0}/openhands/agent_server/conversation_registry.py +0 -0
  29. {openhands_agent_server-1.51.0 → openhands_agent_server-1.53.0}/openhands/agent_server/credential_binding.py +0 -0
  30. {openhands_agent_server-1.51.0 → openhands_agent_server-1.53.0}/openhands/agent_server/dependencies.py +0 -0
  31. {openhands_agent_server-1.51.0 → openhands_agent_server-1.53.0}/openhands/agent_server/docker/Dockerfile +0 -0
  32. {openhands_agent_server-1.51.0 → openhands_agent_server-1.53.0}/openhands/agent_server/docker/build.py +0 -0
  33. {openhands_agent_server-1.51.0 → openhands_agent_server-1.53.0}/openhands/agent_server/docker_runtime/__init__.py +0 -0
  34. {openhands_agent_server-1.51.0 → openhands_agent_server-1.53.0}/openhands/agent_server/docker_runtime/mediation.py +0 -0
  35. {openhands_agent_server-1.51.0 → openhands_agent_server-1.53.0}/openhands/agent_server/docker_runtime/provisioning.py +0 -0
  36. {openhands_agent_server-1.51.0 → openhands_agent_server-1.53.0}/openhands/agent_server/docker_runtime/proxy.py +0 -0
  37. {openhands_agent_server-1.51.0 → openhands_agent_server-1.53.0}/openhands/agent_server/docker_runtime/registry.py +0 -0
  38. {openhands_agent_server-1.51.0 → openhands_agent_server-1.53.0}/openhands/agent_server/docker_runtime/routers.py +0 -0
  39. {openhands_agent_server-1.51.0 → openhands_agent_server-1.53.0}/openhands/agent_server/env_parser.py +0 -0
  40. {openhands_agent_server-1.51.0 → openhands_agent_server-1.53.0}/openhands/agent_server/event_router.py +0 -0
  41. {openhands_agent_server-1.51.0 → openhands_agent_server-1.53.0}/openhands/agent_server/file_router.py +0 -0
  42. {openhands_agent_server-1.51.0 → openhands_agent_server-1.53.0}/openhands/agent_server/git_provider_service.py +0 -0
  43. {openhands_agent_server-1.51.0 → openhands_agent_server-1.53.0}/openhands/agent_server/git_router.py +0 -0
  44. {openhands_agent_server-1.51.0 → openhands_agent_server-1.53.0}/openhands/agent_server/hooks_router.py +0 -0
  45. {openhands_agent_server-1.51.0 → openhands_agent_server-1.53.0}/openhands/agent_server/hooks_service.py +0 -0
  46. {openhands_agent_server-1.51.0 → openhands_agent_server-1.53.0}/openhands/agent_server/init_router.py +0 -0
  47. {openhands_agent_server-1.51.0 → openhands_agent_server-1.53.0}/openhands/agent_server/launch.py +0 -0
  48. {openhands_agent_server-1.51.0 → openhands_agent_server-1.53.0}/openhands/agent_server/llm_router.py +0 -0
  49. {openhands_agent_server-1.51.0 → openhands_agent_server-1.53.0}/openhands/agent_server/local_secret_resolver.py +0 -0
  50. {openhands_agent_server-1.51.0 → openhands_agent_server-1.53.0}/openhands/agent_server/logging_config.py +0 -0
  51. {openhands_agent_server-1.51.0 → openhands_agent_server-1.53.0}/openhands/agent_server/managed_llm_key.py +0 -0
  52. {openhands_agent_server-1.51.0 → openhands_agent_server-1.53.0}/openhands/agent_server/mcp_oauth_store.py +0 -0
  53. {openhands_agent_server-1.51.0 → openhands_agent_server-1.53.0}/openhands/agent_server/mcp_router.py +0 -0
  54. {openhands_agent_server-1.51.0 → openhands_agent_server-1.53.0}/openhands/agent_server/meta_profiles_router.py +0 -0
  55. {openhands_agent_server-1.51.0 → openhands_agent_server-1.53.0}/openhands/agent_server/middleware.py +0 -0
  56. {openhands_agent_server-1.51.0 → openhands_agent_server-1.53.0}/openhands/agent_server/models.py +0 -0
  57. {openhands_agent_server-1.51.0 → openhands_agent_server-1.53.0}/openhands/agent_server/openai/__init__.py +0 -0
  58. {openhands_agent_server-1.51.0 → openhands_agent_server-1.53.0}/openhands/agent_server/openai/models.py +0 -0
  59. {openhands_agent_server-1.51.0 → openhands_agent_server-1.53.0}/openhands/agent_server/openai/service.py +0 -0
  60. {openhands_agent_server-1.51.0 → openhands_agent_server-1.53.0}/openhands/agent_server/openapi.py +0 -0
  61. {openhands_agent_server-1.51.0 → openhands_agent_server-1.53.0}/openhands/agent_server/persistence/__init__.py +0 -0
  62. {openhands_agent_server-1.51.0 → openhands_agent_server-1.53.0}/openhands/agent_server/persistence/models.py +0 -0
  63. {openhands_agent_server-1.51.0 → openhands_agent_server-1.53.0}/openhands/agent_server/persistence/store.py +0 -0
  64. {openhands_agent_server-1.51.0 → openhands_agent_server-1.53.0}/openhands/agent_server/plugins_router.py +0 -0
  65. {openhands_agent_server-1.51.0 → openhands_agent_server-1.53.0}/openhands/agent_server/plugins_service.py +0 -0
  66. {openhands_agent_server-1.51.0 → openhands_agent_server-1.53.0}/openhands/agent_server/profiles_router.py +0 -0
  67. {openhands_agent_server-1.51.0 → openhands_agent_server-1.53.0}/openhands/agent_server/provider_connections_router.py +0 -0
  68. {openhands_agent_server-1.51.0 → openhands_agent_server-1.53.0}/openhands/agent_server/pub_sub.py +0 -0
  69. {openhands_agent_server-1.51.0 → openhands_agent_server-1.53.0}/openhands/agent_server/py.typed +0 -0
  70. {openhands_agent_server-1.51.0 → openhands_agent_server-1.53.0}/openhands/agent_server/runtime_router.py +0 -0
  71. {openhands_agent_server-1.51.0 → openhands_agent_server-1.53.0}/openhands/agent_server/session_protocol.py +0 -0
  72. {openhands_agent_server-1.51.0 → openhands_agent_server-1.53.0}/openhands/agent_server/session_socket.py +0 -0
  73. {openhands_agent_server-1.51.0 → openhands_agent_server-1.53.0}/openhands/agent_server/settings_router.py +0 -0
  74. {openhands_agent_server-1.51.0 → openhands_agent_server-1.53.0}/openhands/agent_server/skills_router.py +0 -0
  75. {openhands_agent_server-1.51.0 → openhands_agent_server-1.53.0}/openhands/agent_server/skills_service.py +0 -0
  76. {openhands_agent_server-1.51.0 → openhands_agent_server-1.53.0}/openhands/agent_server/sockets.py +0 -0
  77. {openhands_agent_server-1.51.0 → openhands_agent_server-1.53.0}/openhands/agent_server/sub_agents_router.py +0 -0
  78. {openhands_agent_server-1.51.0 → openhands_agent_server-1.53.0}/openhands/agent_server/telemetry/__init__.py +0 -0
  79. {openhands_agent_server-1.51.0 → openhands_agent_server-1.53.0}/openhands/agent_server/telemetry/factory.py +0 -0
  80. {openhands_agent_server-1.51.0 → openhands_agent_server-1.53.0}/openhands/agent_server/telemetry/http_exporter.py +0 -0
  81. {openhands_agent_server-1.51.0 → openhands_agent_server-1.53.0}/openhands/agent_server/telemetry/models.py +0 -0
  82. {openhands_agent_server-1.51.0 → openhands_agent_server-1.53.0}/openhands/agent_server/telemetry/policy.py +0 -0
  83. {openhands_agent_server-1.51.0 → openhands_agent_server-1.53.0}/openhands/agent_server/telemetry/posthog_exporter.py +0 -0
  84. {openhands_agent_server-1.51.0 → openhands_agent_server-1.53.0}/openhands/agent_server/telemetry/sanitizer.py +0 -0
  85. {openhands_agent_server-1.51.0 → openhands_agent_server-1.53.0}/openhands/agent_server/telemetry/service.py +0 -0
  86. {openhands_agent_server-1.51.0 → openhands_agent_server-1.53.0}/openhands/agent_server/telemetry/sink.py +0 -0
  87. {openhands_agent_server-1.51.0 → openhands_agent_server-1.53.0}/openhands/agent_server/telemetry/subscriber.py +0 -0
  88. {openhands_agent_server-1.51.0 → openhands_agent_server-1.53.0}/openhands/agent_server/telemetry_types.py +0 -0
  89. {openhands_agent_server-1.51.0 → openhands_agent_server-1.53.0}/openhands/agent_server/tool_preload_service.py +0 -0
  90. {openhands_agent_server-1.51.0 → openhands_agent_server-1.53.0}/openhands/agent_server/tool_router.py +0 -0
  91. {openhands_agent_server-1.51.0 → openhands_agent_server-1.53.0}/openhands/agent_server/utils.py +0 -0
  92. {openhands_agent_server-1.51.0 → openhands_agent_server-1.53.0}/openhands/agent_server/vscode_extensions/openhands-settings/extension.js +0 -0
  93. {openhands_agent_server-1.51.0 → openhands_agent_server-1.53.0}/openhands/agent_server/vscode_extensions/openhands-settings/package.json +0 -0
  94. {openhands_agent_server-1.51.0 → openhands_agent_server-1.53.0}/openhands/agent_server/vscode_router.py +0 -0
  95. {openhands_agent_server-1.51.0 → openhands_agent_server-1.53.0}/openhands/agent_server/vscode_service.py +0 -0
  96. {openhands_agent_server-1.51.0 → openhands_agent_server-1.53.0}/openhands/agent_server/workspace_router.py +0 -0
  97. {openhands_agent_server-1.51.0 → openhands_agent_server-1.53.0}/openhands/agent_server/workspaces_router.py +0 -0
  98. {openhands_agent_server-1.51.0 → openhands_agent_server-1.53.0}/openhands_agent_server.egg-info/SOURCES.txt +0 -0
  99. {openhands_agent_server-1.51.0 → openhands_agent_server-1.53.0}/openhands_agent_server.egg-info/dependency_links.txt +0 -0
  100. {openhands_agent_server-1.51.0 → openhands_agent_server-1.53.0}/openhands_agent_server.egg-info/entry_points.txt +0 -0
  101. {openhands_agent_server-1.51.0 → openhands_agent_server-1.53.0}/openhands_agent_server.egg-info/top_level.txt +0 -0
  102. {openhands_agent_server-1.51.0 → openhands_agent_server-1.53.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.53.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):
@@ -18,6 +18,7 @@ directory in one rename), rolling back if the second fails.
18
18
 
19
19
  import os
20
20
  import shutil
21
+ from contextlib import suppress
21
22
  from pathlib import Path
22
23
 
23
24
  from pydantic import BaseModel, Field, ValidationError
@@ -26,6 +27,7 @@ from openhands.agent_server.canvas_extensions.manifest import (
26
27
  MANIFEST_FILENAME,
27
28
  CanvasExtensionManifest,
28
29
  resolve_entrypoint,
30
+ resolve_icon,
29
31
  )
30
32
  from openhands.sdk.extensions.fetch import fetch_with_resolution
31
33
  from openhands.sdk.extensions.installation import (
@@ -248,6 +250,24 @@ def get_canvas_extension_bundle_path(
248
250
  return resolve_entrypoint(manifest, installed_dir / name)
249
251
 
250
252
 
253
+ def get_canvas_extension_icon_path(
254
+ name: str, installed_dir: Path | None = None
255
+ ) -> Path | None:
256
+ """Resolve *name*'s icon file, re-checking containment like the bundle.
257
+
258
+ Returns:
259
+ None if not installed, no icon is declared, or the icon doesn't resolve
260
+ to a contained file. A broken icon never affects the manifest itself.
261
+ """
262
+ installed_dir = _resolve_installed_dir(installed_dir)
263
+ manifest = get_installed_canvas_extension_manifest(name, installed_dir)
264
+ if manifest is None:
265
+ return None
266
+ with suppress(ValueError, OSError):
267
+ return resolve_icon(manifest, installed_dir / name)
268
+ return None
269
+
270
+
251
271
  class CanvasExtensionUpdateCheck(BaseModel):
252
272
  """Result of ``check_canvas_extension_update``.
253
273
 
@@ -21,6 +21,10 @@ from typing import Final, Literal
21
21
  from pydantic import BaseModel, Field, field_validator, model_validator
22
22
 
23
23
  from openhands.sdk.extensions.installation.utils import validate_extension_name
24
+ from openhands.sdk.logger import get_logger
25
+
26
+
27
+ logger = get_logger(__name__)
24
28
 
25
29
 
26
30
  # Filename a canvas extension's manifest is loaded from, at its package root.
@@ -181,6 +185,25 @@ class CanvasExtensionManifest(BaseModel):
181
185
  exclude_if=lambda value: value is None,
182
186
  description="Optional explicitly prepared and started backend service",
183
187
  )
188
+ icon: str | None = Field(
189
+ default=None,
190
+ exclude_if=lambda value: value is None,
191
+ description="Path, relative to the extension package root, to an SVG icon",
192
+ )
193
+
194
+ @field_validator("icon", mode="before")
195
+ @classmethod
196
+ def _validate_icon(cls, v: object) -> str | None:
197
+ """Drop a non-SVG icon instead of raising.
198
+
199
+ The manifest is re-validated on every read, so raising here would hide
200
+ the whole extension. Containment is checked at serve time by
201
+ :func:`resolve_icon`.
202
+ """
203
+ if v is None or (isinstance(v, str) and v.endswith(".svg")):
204
+ return v
205
+ logger.warning("Ignoring invalid canvas extension icon %r", v)
206
+ return None
184
207
 
185
208
  @field_validator("schema_version")
186
209
  @classmethod
@@ -237,16 +260,32 @@ def resolve_entrypoint(manifest: CanvasExtensionManifest, package_root: Path) ->
237
260
  a directory, a dangling symlink, and symlink cycles — none of
238
261
  which ``is_relative_to`` alone rejects).
239
262
  """
263
+ return _resolve_contained_file("entrypoint", manifest.entrypoint, package_root)
264
+
265
+
266
+ def resolve_icon(manifest: CanvasExtensionManifest, package_root: Path) -> Path | None:
267
+ """Resolve ``manifest.icon`` with the same containment check as the entrypoint.
268
+
269
+ Returns:
270
+ None if the manifest declares no icon.
271
+
272
+ Raises:
273
+ ValueError: If the icon escapes ``package_root`` or is not a file.
274
+ """
275
+ icon = manifest.icon
276
+ return None if icon is None else _resolve_contained_file("icon", icon, package_root)
277
+
278
+
279
+ def _resolve_contained_file(label: str, relative_path: str, package_root: Path) -> Path:
240
280
  root = package_root.resolve()
241
- candidate = (root / manifest.entrypoint).resolve()
281
+ candidate = (root / relative_path).resolve()
242
282
  if not candidate.is_relative_to(root):
243
283
  raise ValueError(
244
- f"entrypoint {manifest.entrypoint!r} resolves outside the "
245
- "extension package root"
284
+ f"{label} {relative_path!r} resolves outside the extension package root"
246
285
  )
247
286
  if not candidate.is_file():
248
287
  raise ValueError(
249
- f"entrypoint {manifest.entrypoint!r} does not resolve to a file "
288
+ f"{label} {relative_path!r} does not resolve to a file "
250
289
  "in the extension package"
251
290
  )
252
291
  return candidate
@@ -26,6 +26,7 @@ from openhands.agent_server.canvas_extensions.installed import (
26
26
  disable_canvas_extension,
27
27
  enable_canvas_extension,
28
28
  get_canvas_extension_bundle_path,
29
+ get_canvas_extension_icon_path,
29
30
  get_installed_canvas_extension,
30
31
  get_installed_canvas_extension_manifest,
31
32
  install_canvas_extension,
@@ -437,3 +438,42 @@ def get_canvas_extension_bundle_endpoint(
437
438
  detail=f"Canvas extension '{extension_name}' bundle not found",
438
439
  )
439
440
  return FileResponse(bundle_path, headers={"Cache-Control": "no-cache"})
441
+
442
+
443
+ @canvas_extensions_router.get(
444
+ "/installed/{extension_name}/icon",
445
+ response_class=FileResponse,
446
+ responses={
447
+ 200: {
448
+ "content": {
449
+ "image/svg+xml": {"schema": {"type": "string", "format": "binary"}}
450
+ }
451
+ },
452
+ 404: {"description": "Canvas extension or icon not found"},
453
+ },
454
+ )
455
+ def get_canvas_extension_icon_endpoint(
456
+ extension_name: CanvasExtensionNamePath,
457
+ ) -> FileResponse:
458
+ """Serve the SVG icon declared by an installed canvas extension's manifest.
459
+
460
+ The path comes from the manifest, never the request. The CSP sandbox keeps
461
+ a directly opened SVG from running scripts on the agent-server origin.
462
+ """
463
+ icon_path = get_canvas_extension_icon_path(name=extension_name)
464
+ if icon_path is None:
465
+ raise HTTPException(
466
+ status_code=404,
467
+ detail=f"Canvas extension '{extension_name}' icon not found",
468
+ )
469
+ return FileResponse(
470
+ icon_path,
471
+ media_type="image/svg+xml",
472
+ headers={
473
+ "Cache-Control": "no-cache",
474
+ "Content-Security-Policy": (
475
+ "default-src 'none'; style-src 'unsafe-inline'; sandbox"
476
+ ),
477
+ "X-Content-Type-Options": "nosniff",
478
+ },
479
+ )
@@ -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: