Show agent-server version errors for workspaces

[neubig]

Summary

• pin to the draft typescript-client branch that exports AgentServerVersionError and workspace compatibility helpers
• preflight workspace API calls so old agent servers surface a typed version error instead of a 404
• disable local workspace launch/add controls and show a tooltip/status message with the running and required agent-server versions

Depends on OpenHands/typescript-client#176.

Human Verification

HUMAN: I can confirm that this worked on my running agent canvas

Verification

• npm test -- __tests__/api/workspaces-service.test.ts __tests__/components/features/home/workspace-selection-form.test.tsx __tests__/components/features/home/home-chat-launcher.test.tsx __tests__/components/features/conversation-panel/local-new-conversation-menu.test.tsx
• npm run typecheck
• npm run build
• npm run lint

---

🐳 Docker images for this PR

• GHCR package: https://github.com/OpenHands/agent-canvas/pkgs/container/agent-canvas

Component	Value
Image	ghcr.io/openhands/agent-canvas
Architectures	amd64, arm64
Agent Server	ghcr.io/openhands/agent-server:1.23.0-python
Automation	openhands-automation==1.0.0a3
Commit	b2ef07c07fcf9f11c28545af08fbcd946ca64505

Pull (multi-arch manifest)

# Multi-arch manifest — Docker automatically pulls the correct architecture
docker pull ghcr.io/openhands/agent-canvas:sha-b2ef07c

Run

docker run -it --rm \
  -p 8000:8000 \
  ghcr.io/openhands/agent-canvas:sha-b2ef07c

All tags pushed for this build

ghcr.io/openhands/agent-canvas:sha-b2ef07c-amd64
ghcr.io/openhands/agent-canvas:codex-workspaces-old-server-tooltip-amd64
ghcr.io/openhands/agent-canvas:pr-742-amd64
ghcr.io/openhands/agent-canvas:sha-b2ef07c-arm64
ghcr.io/openhands/agent-canvas:codex-workspaces-old-server-tooltip-arm64
ghcr.io/openhands/agent-canvas:pr-742-arm64
ghcr.io/openhands/agent-canvas:sha-b2ef07c
ghcr.io/openhands/agent-canvas:codex-workspaces-old-server-tooltip
ghcr.io/openhands/agent-canvas:pr-742

About Multi-Architecture Support

• Each tag (e.g., sha-b2ef07c) is a multi-arch manifest supporting both amd64 and arm64
• Docker automatically pulls the correct architecture for your platform
• Individual architecture tags (e.g., sha-b2ef07c-amd64) are also available if needed

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
agent-canvas	Ready	Preview, Comment	May 23, 2026 12:47pm

[all-hands-bot]

Taste Rating: 🟢 Good taste - Clean implementation with proper error typing and consistent UX patterns.

[DEPENDENCY NOTE]

This PR depends on @openhands/typescript-client branch codex/agent-server-version-errors (OpenHands/typescript-client#176), pinned to commit 255df0c. The dependency is well-managed with lockfile pinning and explicit documentation in the PR description. This follows the repo's established pattern for depending on unreleased typescript-client features during active development (see AGENTS.md note about commit pinning).

Once the upstream PR merges, consider updating to a tagged release or main branch ref.

[IMPLEMENTATION HIGHLIGHTS]

• Clean abstraction: The getWorkspacesUnsupportedMessage helper centralizes error detection and message formatting
• Proper preflight: Service layer calls assertAgentServerSupports before each workspace API call, preventing 404s
• Consistent UX: Disabled controls + tooltips across all workspace entry points (home, sidebar, dropdowns)
• Good test coverage: Service layer, hooks, and component-level tests verify the typed error propagates correctly
• i18n ready: Version-aware error messages with interpolated version numbers

[RISK ASSESSMENT]

• [Overall PR] ⚠️ Risk Assessment: 🟡 MEDIUM

The implementation quality is high and test coverage is thorough. The medium risk rating reflects the dependency on unreleased upstream code rather than code quality concerns. The functional changes are additive - they improve error messaging for a scenario that already didn't work (old servers + workspaces), without affecting users on supported servers (>= 1.23.0).

VERDICT:
✅ Worth merging: Solid implementation that replaces confusing 404s with helpful version-specific error messages. The upstream dependency is well-managed and explicitly documented.

KEY INSIGHT:
Proper use of SDK-provided typed errors (AgentServerVersionError) enables graceful degradation and actionable user feedback when agent-server versions don't support workspace features.

---

Was this automated review useful? React with 👍 or 👎 to this review to help us measure review quality.
Workflow run: https://github.com/OpenHands/agent-canvas/actions/runs/26331878271

[all-hands-bot]

Taste Rating: 🟢 Good taste - Clean implementation with proper error typing and consistent UX patterns.

The version error preflight in workspaces-service.api.ts is elegant: typed errors flow cleanly through the UI layer, enabling graceful degradation (disable + tooltip) instead of cryptic 404s. Test coverage validates the error paths, and centralized message extraction in workspaces-compatibility.ts keeps it maintainable.

[RISK ASSESSMENT]

• [Overall PR] ⚠️ Risk Assessment: 🟢 LOW

Infrastructure enhancement for version compatibility checking. Additive change with graceful degradation, good test coverage, no breaking changes.

VERDICT:
✅ Worth merging

---

Was this automated review useful? React with 👍 or 👎 to this review to help us measure review quality.
Workflow run: https://github.com/OpenHands/agent-canvas/actions/runs/26332299806

[github-actions]

📸 Snapshot Test Report

Warning

Snapshot comparison step crashed (timeout, OOM, or runner error) — diff results below may be incomplete or absent.
Check the CI logs for the full error output (look for the "Run snapshot comparison" step).

✅ 2 snapshots changed — acknowledged via the update-snapshots label. New baselines will be uploaded when this PR merges.

Category	Count
🔴 Changed	2
🆕 New	0
✅ Unchanged	71
Total	73

🔴 Changed snapshots (2)

backends-extended — 2 snapshots

backend-cancel-nothing-saved

Expected (main)	Actual (PR)	Diff

backend-manage-two-listed

Expected (main)	Actual (PR)	Diff

✅ Unchanged snapshots (71)

archived-conversation

• conversation-panel-with-archived-badges
• conversation-view-archived
• conversation-view-sandbox-error

automations

• automations-delete-modal
• automations-list-active-inactive
• automations-no-automations
• automations-search-no-results

backends-extended

• backend-add-blank-disabled
• backend-add-cloud-advanced-open
• backend-add-cloud-no-key-disabled
• backend-add-cloud-with-key-enabled
• backend-add-form-partially-filled
• backend-add-invalid-url-disabled
• backend-add-local-ready
• backend-add-name-only-disabled
• backend-add-two-column-layout
• backend-add-whitespace-host-disabled
• backend-after-switch
• backend-dropdown-two-backends
• backend-edit-prefilled
• backend-manage-after-removal
• backend-remove-cancelled
• backend-remove-confirmation
• backend-switch-overlay

backends

• backend-add-modal
• backend-manage-modal
• backend-selector-open

changes-tab

• changes-deleted-file
• changes-diff-viewer
• changes-empty

collapsible-thinking

• reasoning-content-collapsed
• reasoning-content-expanded
• think-action-collapsed
• think-action-expanded

mcp-page

• mcp-custom-server-1-editor-open
• mcp-custom-server-2-url-filled
• mcp-custom-server-3-all-filled
• mcp-custom-server-4-installed
• mcp-custom-server-editor
• mcp-empty-installed
• mcp-search-filtered
• mcp-slack-install-1-marketplace
• mcp-slack-install-2-modal
• mcp-slack-install-3-filled
• mcp-slack-install-4-installed

onboarding

• onboarding-step-0-choose-agent
• onboarding-step-1-check-backend
• onboarding-step-2-setup-llm
• onboarding-step-3-say-hello

projects-workspace-browser

• projects-workspace-browser

settings-page

• add-backend-modal
• analytics-consent-modal
• home-screen
• settings-app-page
• settings-page

settings-secrets

• secrets-add-form-filled
• secrets-add-form
• secrets-after-save
• secrets-delete-confirm
• secrets-list

settings-verification

• condenser-settings
• verification-settings-off
• verification-settings-on

sidebar

• sidebar-collapsed
• sidebar-conversation-panel
• sidebar-filter-menu

skills-page

• skills-empty
• skills-loaded
• skills-no-match
• skills-search-filtered
• skills-type-filter

---

Generated by the Snapshot Tests workflow. This comment was created by an AI agent (OpenHands) on behalf of the repo maintainers.