fix(conversations): OHE-3432 return an Agent Canvas link in the API

[lilagrc]

HUMAN:

• A human has tested these changes.

Manually verified this, along with OpenHands/OpenHands#17842 and OpenHands/extensions#714, produced the correct, canvas conversation link when for a sub agent delegated conversation.

AGENT:

---

Why

When an agent hands work to a sub-agent through POST /api/v1/app-conversations, the link it gives the user opens the legacy UI at /conversations/<id>, not Agent Canvas. The API gives the agent no browser link to use. The only URL on the conversation record is conversation_url, which points at the sandbox's agent-server API. So agents build the link themselves from the openhands-api skill, which uses the legacy route.

Summary

• AppConversation has a new conversation_ui_url field: <web_url>/canvas/conversations/<id>. It is None when no web URL is configured. It is filled in inside _build_conversation, which every endpoint that returns a conversation goes through, including GET /api/v1/app-conversations?ids=.
• The link uses the configured web URL, not the service's own web_url. With no web URL configured, the service's value falls back to a host.docker.internal address that only sandboxes can reach.
• The field is additive and already-configured deployments need no new settings. Server-generated links from the integrations and the MCP router already point to /canvas/conversations/.

Issue Number

Refs #598 (OHE-3432). This is the backend part only; see Notes.

How to Test

• uv run pytest tests/unit/app_server/test_conversation_ui_url.py. There are four tests. They were written first and failed with the field missing; they pass now. The main one saves a conversation to the Postgres test database the way an API-started delegation stores it, reads it back through batch_get_app_conversations, and checks for the Canvas link.
• uv run pytest tests/unit/app_server/test_live_status_app_conversation_service.py: 213 passed.
• Wider run over tests/unit/app_server and tests/unit/server/routes: everything passes except 17 quota tests. Those return 401 because the sandbox sets SESSION_API_KEY; they fail the same way on main and pass with it unset.
• Manual: start a conversation through the API, then GET /api/v1/app-conversations?ids=<id> should return conversation_ui_url pointing at /canvas/conversations/<id>.

Video/Screenshots

None. The change only adds an API field.

Type

• Bug fix
• Feature
• Refactor
• Breaking change
• Docs / chore

Notes

Follow-ups outside this repo:

• openhands-api skill (OpenHands/extensions): share conversation_ui_url, fall back to <HOST>/canvas/conversations/<id> on older servers, and drop the hardcoded app.all-hands.dev.
• Agent Canvas (OpenHands/OpenHands): launchCloudChild in src/services/child-conversation-launch.ts also returns the legacy /conversations/<id> link for Cloud child conversations.

This PR does not set parent_conversation_id for delegated conversations. That field makes the child share the parent's sandbox, hides it from /search (Canvas never asks for sub-conversations), and deletes it along with the parent.

This PR was drafted by an AI agent on behalf of the user.

@lilagrc can click here to continue refining the PR

---

Enterprise server image for this PR:

ghcr.io/openhands/enterprise-server:sha-c2462be

[github-actions]

Coverage report

Click to see where and how coverage changed

File	Statements	Missing	Coverage	Coverage (new stmts)	Lines missing
openhands/app_server/app_conversation
app_conversation_models.py
conversation_links.py
live_status_app_conversation_service.py
Project Total

This report was generated by python-coverage-comment-action

[openhands-release-bot]

🚀 Released in 1.68.0.