refactor(api): use typescript-client ConversationClient + FileClient instead of hand-written HTTP paths

[rbren]

What

Pushes 12 hand-written createHttpClient().{get,post,patch,delete} call sites in AgentServerConversationService / FilesService / agent-server-adapter down to the typed ConversationClient and FileClient that the typescript-client SDK already ships. No new endpoints, no new request shapes — agent-canvas was duplicating the SDK by hand with looser types.

This PR was opened by an AI agent (OpenHands) on behalf of @rbren. Companion to #288 / #290.

Why

Today, every method in AgentServerConversationService writes the URL string literal itself (e.g. `/api/conversations/${id}/pause`) and types the response inline ({success: boolean}). The SDK has:

• ConversationClient.{createConversation, getConversation, getConversations, searchConversations, sendEvent, pauseConversation, runConversation, askAgent, updateConversation, deleteConversation, …}
• FileClient.{getHome, searchSubdirectories, downloadFile, downloadTextFile, downloadTrajectory}

…all already imported transitively through @openhands/typescript-client/clients, with proper request/response types in models/conversation.ts and models/api.ts. So the right fix is to use them.

Mapping

Before (raw HTTP)	After (typed client)
createHttpClient().post('/api/conversations/:id/events', {...msg, run:true})	ConversationClient.sendEvent(id, msg, { run: true })
createHttpClient().post<DirectConversationInfo>('/api/conversations', payload)	ConversationClient.createConversation<DirectConversationInfo>(payload)
createHttpClient({sessionApiKey}).post('/api/conversations/:id/pause', {})	ConversationClient.pauseConversation(id) (with {sessionApiKey})
createHttpClient({sessionApiKey}).post('/api/conversations/:id/run', {})	ConversationClient.runConversation(id)
createHttpClient({sessionApiKey}).post('/api/conversations/:id/ask_agent', {q})	ConversationClient.askAgent(id, q)
createHttpClient().get('/api/conversations', { params: { ids } })	ConversationClient.getConversations<DirectConversationInfo>(ids)
createHttpClient().get('/api/conversations/search', { params: … })	ConversationClient.searchConversations({limit, page_id, sort_order: ConversationSortOrder.UPDATED_AT_DESC})
createHttpClient().delete('/api/conversations/:id')	ConversationClient.deleteConversation(id)
createHttpClient().patch('/api/conversations/:id', {title})	ConversationClient.updateConversation(id, {title})
createHttpClient({conversationUrl, sessionApiKey}).get('/api/conversations/:id')	ConversationClient.getConversation<RawRuntime>(id) (same overrides)
createHttpClient().get<Blob>('/api/file/download-trajectory/:id', {responseType:'blob'})	FileClient.downloadTrajectory(id)
createHttpClient().get<ArrayBuffer>('/api/file/download', { params: {path}, responseType:'arrayBuffer' })	FileClient.downloadTextFile(path)
createHttpClient().get('/api/file/search_subdirs', { params: … })	FileClient.searchSubdirectories(path, {pageId, limit})
createHttpClient().get('/api/file/home')	FileClient.getHome()

New factories

Two thin wrappers on top of the existing resolveClientOptions(overrides) helper in src/api/typescript-client.ts:

export function createConversationClient(overrides?: TypeScriptClientOverrides): ConversationClient
export function createFileClient(overrides?: TypeScriptClientOverrides): FileClient

They take the same { sessionApiKey, conversationUrl, … } shape as createHttpClient, so per-call host / session-key overrides keep working exactly the same (used by pauseConversation, getRuntimeConversation, etc.).

Notes

• One cast, explained. Local-mode searchConversations casts ConversationInfo[] (SDK type) → DirectConversationInfo[] (agent-canvas's narrower view of the same JSON) through unknown. The comment in-file explains why; both types describe the same agent-server response, just different reads of it.
• Cloud paths unchanged. Every method's cloud branch already goes through callCloudProxy (because cross-origin to *.prod-runtime.all-hands.dev doesn't work from localhost); those paths are untouched.
• SecretsService.getSecrets is still on raw createHttpClient. The retry + fallback-to-empty-array pattern there would interact awkwardly with this PR's test mocks if migrated in the same patch. Flagged as follow-up below.

Verification

$ npm run typecheck                # passes
$ npm run lint                     # 0 errors, same 10 pre-existing warnings
$ npx vitest run                   # 286 files | 1862 passed | 12 skipped | 9 todo

Two test files needed mock updates — both now mock the new client factories with typed shapes instead of the old {get, post, patch, delete} http-client mock. Same coverage, but the assertions read more naturally (expect(mockDownloadTrajectory).toHaveBeenCalledWith("conv-abc") vs. expect(mockHttpGet).toHaveBeenCalledWith("/api/file/download-trajectory/conv-abc", { responseType: "blob" })).

Additional findings (not addressed in this PR)

From the broader code-review pass on this repo, these are worth follow-up PRs (decreasing order of value):

1. SecretsService (src/api/secrets-service.ts) and cloud/organization-service.api.ts are still on raw createHttpClient. Same pattern — the SDK has neither a SecretsClient nor an OrganizationClient yet, so this would be a typescript-client PR first. Worth doing because both surfaces would benefit from typed responses.
2. Cloud-mode RemoteWorkspace. src/api/git-service/agent-server-git-service.api.ts hand-routes /api/git/{changes,diff} through callCloudProxy because the SDK's RemoteWorkspace.gitChanges/gitDiff always talks directly to its configured host (which CORS-fails against *.prod-runtime.all-hands.dev from a browser). A genuine SDK-side feature would be a RemoteWorkspace constructor option that takes a transport callback (or a CloudRemoteWorkspace subclass), letting the SDK do path normalization + auth uniformly across both modes. This is the next-substantive PR I'd recommend.
3. toAbsoluteRuntimePath workaround in agent-server-git-service.api.ts (the cloud runtime double-prepends /workspace/ to relative paths). Should be fixed on the runtime side. Currently the workaround lives in two places (getGitChanges, getGitDiff) — fine, but worth a TODO link to whatever runtime issue tracks the dupe-prefix bug.
4. Translations cleanup. Several leftover keys from the OSS cleanup (TOS$ACCEPT, etc.) appear in src/i18n/translation.json with no t(I18nKey.…) consumers. A dead-string sweep could quietly remove them.
5. Vitest run time. ~5.5 min for 1862 tests with environment: 406s dominating; suggests cost of happy-dom setup. Worth experimenting with shared environments / pool: 'threads' on CI.
6. Accessibility sweep. Quick grep finds several icon-only buttons (src/components/features/file-explorer/file-diff-viewer.tsx:240 collapse, the refresh button I already fixed in chore: address post-merge feedback on #284 + small code-review fixes #288, and a few <button> in src/components/features/conversation/…). A targeted axe-driven pass would be cheap and high-ROI.

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
agent-canvas	Error		May 12, 2026 2:28am

[all-hands-bot]

Taste Rating: 🟢 Good taste - Clean refactor that improves type safety by replacing hand-written HTTP calls with typed SDK clients.

[RISK ASSESSMENT]

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

Internal refactoring only. No user-facing changes, no agent behavior changes, no eval impact. The SDK clients (ConversationClient, FileClient) wrap the same HTTP endpoints with proper types. The two casts (payload as Record<string, unknown> and ConversationInfo[] as unknown as DirectConversationInfo[]) are explained and safe. Tests updated and passing (1862 passed).

VERDICT:
✅ Worth merging - Improves type safety and reduces hand-written HTTP boilerplate without changing behavior.

KEY INSIGHT:
This PR demonstrates the right way to adopt SDK clients: migrate incrementally (12 call sites), keep behavior identical, explain necessary casts, and flag remaining work (SecretsService) for follow-up.

[rbren]

@OpenHands fix failing gh action

[openhands-ai]

I'm on it! rbren can track my progress at all-hands.dev

[openhands-ai]

OpenHands encountered an error: Request timeout after 30 seconds to https://sjvnzhqjmpxwzjfi.prod-runtime.all-hands.dev/api/conversations/8837e85a-68bd-4938-9670-68a792025ffe/ask_agent

See the conversation for more information.