Start conversations from backend-stored settings

[neubig]

Summary

Start new conversations using backend-stored settings instead of having the browser build and send the full runnable Agent payload.

This is the GUI counterpart to the remaining settings-backed conversation creation work in OpenHands/software-agent-sdk#3034.

Current behavior

src/api/conversation-service/v1-conversation-service.api.ts currently:

1. calls SettingsService.getSettings();
2. calls buildStartConversationRequest({ settings, ... }) from src/api/agent-server-adapter.ts;
3. posts a full payload to /api/conversations containing agent, workspace, confirmation_policy, security_analyzer, max_iterations, plugins, etc.

Once settings are backend-owned, this can drift from SDK behavior and can require browser access to secret-bearing configuration.

Dependencies

Requires an agent-server API/capability that can start conversations from persisted settings, as specified in the remaining work on OpenHands/software-agent-sdk#3034.

Keep compatibility fallback for older agent-server versions until the minimum supported version is raised.

Desired request behavior

On supported backends, V1ConversationService.createConversation() sends only runtime inputs and explicit per-run overrides, for example:

{
  "use_stored_settings": true,
  "workspace": { "kind": "LocalWorkspace", "working_dir": "workspace/project" },
  "initial_message": {
    "role": "user",
    "content": [{ "type": "text", "text": "..." }]
  },
  "plugins": [],
  "agent_settings_diff": {},
  "conversation_settings_diff": {}
}

The exact field names should match the SDK API that lands. The invariant is:

• the browser does not send agent.llm.api_key;
• the browser does not send a full agent object in the default settings-backed path;
• the server constructs the runnable agent from persisted settings.

Implementation requirements

1. Add capability detection for settings-backed conversation creation.
   • Prefer explicit server capability metadata if available.
   • Otherwise gate by the agent-server version where the SDK feature lands.
2. Update V1ConversationService.createConversation() to use the settings-backed request on supported servers.
3. Keep legacy fallback to buildStartConversationRequest() for unsupported servers.
4. Preserve runtime-only values:
   • initial user message;
   • conversation instructions;
   • selected working directory;
   • plugins;
   • plan/subconversation metadata if applicable;
   • explicit one-off settings overrides, if a UI flow supplies them.
5. Remove SettingsService.getSettings() from the normal conversation-start path on supported servers.
6. Keep conversation response adaptation unchanged unless the backend response contract changes.

Acceptance criteria

• Supported backend path does not call SettingsService.getSettings() solely to build a conversation-start request.
• Supported backend payload does not contain a full agent object.
• Supported backend payload does not contain raw LLM API keys or provider tokens.
• Workspace, initial message, conversation instructions, and plugins are still represented correctly.
• Unsupported/older backends still work through the existing fallback builder.
• Tests cover both supported and fallback server capabilities.
• buildStartConversationRequest() is reduced to fallback-only use or clearly marked/tested as legacy behavior.

Suggested tests

• __tests__/api/v1-conversation-service.test.ts
  • supported backend: payload has use_stored_settings or canonical equivalent and no agent;
  • fallback backend: existing payload builder still used;
  • payload includes workspace, initial message, and plugins;
  • no raw secret fields are sent.
• __tests__/api/agent-server-adapter.test.ts
  • legacy builder tests remain but are scoped to fallback behavior.

Non-goals

• Backend settings persistence.
• Multi-backend switching.
• Removing UI-only localStorage conversation tab/draft state.
• Settings page persistence changes; that is tracked in Use backend-persisted settings and secrets instead of localStorage #68.

Related prior work

Closed GUI issue #37 aligned conversation startup with nested SDK settings on the client side. This issue is different: it moves default runnable agent construction to the backend once backend-persisted settings exist.

---

This issue was created by an AI agent (OpenHands) on behalf of the user.