📄 openhands/app_server/app_conversation/app_conversation_models.py (第 125 行)

class AppConversationInfo(BaseModel):
    """Conversation info which does not contain status."""

    id: OpenHandsUUID = Field(default_factory=uuid4)
    # ...
    agent_kind: str = 'openhands'
    # ...

    @computed_field
    @property
    def acp_server(self) -> str | None:
        """Active ACP provider key ('claude-code', 'codex', 'gemini-cli'), else None."""
        if self.agent_kind != 'acp':
            return None
        return self.tags.get(ACP_SERVER_TAG_KEY)

📄 openhands/app_server/app_conversation/app_conversation_models.py (第 64-69 行)

class AgentType(Enum):
    """Agent type for conversation."""

    DEFAULT = 'default'
    PLAN = 'plan'

📄 openhands/app_server/settings/settings_models.py (第 40-48 行)

from openhands.sdk.settings import (
    ACPAgentSettings,
    AgentSettingsConfig,
    ConversationSettings,
    OpenHandsAgentSettings,
    apply_agent_settings_diff,
    default_agent_settings,
    validate_agent_settings,
)

📄 openhands/app_server/settings/settings_models.py (第 706 行)

class Settings(BaseModel):
    # ...
    agent_settings: AgentSettingsConfig = Field(
        default_factory=default_agent_settings
    )
    # ...

📄 openhands/app_server/settings/settings_models.py (第 852-855 行)

# The SDK owns the discriminated-union merge: replace on
# ``agent_kind`` change, deep-merge within a variant. Cross-kind
# config preservation tracked in OpenHands/OpenHands#14370.
new_settings = apply_agent_settings_diff(self.agent_settings, coerced)

📄 tests/unit/app_server/test_settings_agent_kind_switch.py (第 49-64 行)

def test_kind_switch_does_not_raise():
    """OH → ACP → OH must not 500."""
    s = Settings()
    s.update(_set_openhands(llm_model='anthropic/claude-sonnet-4-5'))

    s.update(_set_acp())
    assert s.agent_settings.agent_kind == 'acp'

    s.update(_set_openhands())
    assert s.agent_settings.agent_kind == 'openhands'


def test_kind_switch_resets_new_kind_to_defaults():
    """Switching to a new kind starts from a fresh base."""
    s = Settings()
    s.update(_set_openhands(llm_model='anthropic/claude-sonnet-4-5'))
    s.update(_set_acp())
    # ACP base — llm defaults to the ACP sentinel, not the OH model.
    assert s.agent_settings.agent_kind == 'acp'
    assert s.agent_settings.llm.model != 'anthropic/claude-sonnet-4-5'

📄 openhands/app_server/app_conversation/live_status_app_conversation_service.py (第 570-585 行)

if request_agent.agent_kind == 'acp':
    llm_model = request_agent.acp_model
    agent_kind = 'acp'
    # Persist the active ACP provider key so the conversation UI
    # can resolve a brand label ("Claude Code", "Codex", …) via
    # the SDK registry without keeping a per-conversation column.
    if isinstance(profile_user.agent_settings, ACPAgentSettings):
        tags[ACP_SERVER_TAG_KEY] = profile_user.agent_settings.acp_server
else:
    llm_model = request_agent.llm.model
    agent_kind = 'openhands'

📄 openhands/app_server/app_conversation/live_status_app_conversation_service.py (第 2379-2407 行)

# --- build the ACP agent ------------------------------------------
acp_settings = user.agent_settings  # already verified to be ACPAgentSettings
assert isinstance(acp_settings, ACPAgentSettings)

# Isolate the CLI data dir onto the durable /workspace tree so the SDK
# self-resumes the provider session (session/load from base_state.json)
# across pause/resume — matching the regular-agent lifecycle (#1274).
# Strip llm.api_key/base_url to prevent proxy settings from leaking
# into the subprocess env (ACP CLIs handle their own LLM calls).
settings_update: dict[str, Any] = {
    'acp_isolate_data_dir': True,
    'llm': acp_settings.llm.model_copy(
        update={'api_key': None, 'base_url': None}
    ),
}
# Forward the resolved profile's / user's custom MCP servers to the ACP
# subprocess (#15044 §7). Only custom servers — the system OpenHands MCP
# server (Tavily proxy) is runtime-internal and unreachable by an external
# ACP CLI, so it is intentionally not injected here.
acp_mcp_servers: dict[str, MCPServer] = {}
self._merge_custom_mcp_config(acp_mcp_servers, user)
if acp_mcp_servers:
    settings_update['mcp_config'] = acp_mcp_servers
if system_message_suffix:
    settings_update['agent_context'] = AgentContext(
        system_message_suffix=system_message_suffix
    )
acp_settings_for_agent = acp_settings.model_copy(update=settings_update)
acp_agent = acp_settings_for_agent.create_agent()

📄 openhands/app_server/settings/agent_profiles.py (第 43-55 行)

from openhands.sdk.profiles import (
    ACPAgentProfile,
    OpenHandsAgentProfile,
    ProfileLimitExceeded,
    validate_agent_profile,
)

MAX_AGENT_PROFILES: Final[int] = 50

_AgentProfile: TypeAlias = OpenHandsAgentProfile | ACPAgentProfile

📄 openhands/app_server/settings/agent_profiles.py (第 134-154 行)

def list_summaries(self) -> _ProfileSummaries:
    """Metadata projection {id, name, agent_kind, revision,
    llm_profile_ref, mcp_server_refs} per profile."""
    summaries: list[dict[str, Any]] = []
    for pid, profile in self.profiles.items():
        summaries.append(
            {
                'id': pid,
                'name': profile.name,
                'agent_kind': profile.agent_kind,
                'revision': profile.revision,
                'llm_profile_ref': (
                    profile.llm_profile_ref
                    if isinstance(profile, OpenHandsAgentProfile)
                    else None
                ),
                'mcp_server_refs': profile.mcp_server_refs,
            }
        )
    return summaries

📄 openhands/app_server/app_conversation/app_conversation_models.py (第 30-48 行)

# Canonical conversation-tag key under which the active ACP provider key
# ('claude-code', 'codex', 'gemini-cli') is stored. Synced with agent-canvas.
# Constrained to ^[a-z0-9]+$ by the SDK validator — no underscores allowed.
# The typed ``AppConversationInfo.acp_server`` field is a projection of this tag.
ACP_SERVER_TAG_KEY = 'acpserver'

# Conversation-tag key pinning the resolved (grouped) workspace path at creation
ARCHIVE_WORKSPACE_PATH_TAG_KEY = 'archiveworkspacepath'

# Conversation-tag keys recording which Agent Profile launched the conversation
AGENT_PROFILE_ID_TAG_KEY = 'agentprofileid'
AGENT_PROFILE_REVISION_TAG_KEY = 'agentprofilerevision'

📄 openhands/app_server/event_callback/webhook_router.py (第 333-359 行)

async def _resolve_acp_server_key(agent: Any, user_id: str | None) -> str | None:
    """Resolve the ACP provider key for a conversation whose tag is not yet set.

    Prefer the conversation's own launch command (ACPAgent.acp_command): it
    is authoritative for the agent that is actually running and matched against
    the SDK registry by detect_acp_provider_by_command. Only fall back to the
    user's saved settings when the command is unknown (a custom server) or absent
    (older agent payloads).
    """
    command = getattr(agent, 'acp_command', None)
    if command:
        provider = detect_acp_provider_by_command(command)
        if provider is not None:
            return provider.key
    try:
        settings_store = await shared.SettingsStoreImpl.get_instance(user_id)
        settings = await settings_store.load() if settings_store else None
        agent_settings = getattr(settings, 'agent_settings', None)
        if isinstance(agent_settings, ACPAgentSettings):
            return agent_settings.acp_server
    except Exception:
        _logger.warning(
            'Failed to resolve ACP server key for user %s', user_id, exc_info=True
        )
    return None

📄 openhands/app_server/app_conversation/app_conversation_models.py (第 50-61 行)

class ConversationTrigger(Enum):
    RESOLVER = 'resolver'
    GUI = 'gui'
    SUGGESTED_TASK = 'suggested_task'
    REMOTE_API_KEY = 'openhands_api'
    SLACK = 'slack'
    MICROAGENT_MANAGEMENT = 'microagent_management'
    JIRA = 'jira'
    JIRA_DC = 'jira_dc'
    LINEAR = 'linear'
    BITBUCKET = 'bitbucket'
    AUTOMATION = 'automation'

📄 openhands/app_server/event_callback/webhook_router.py (第 392-397 行)

# Determine trigger - check if tags indicate automation, then fall back to existing
trigger = detect_automation_trigger(
    existing.trigger,
    merged_tags,
    conversation_id=str(conversation_info.id),
    sandbox_id=sandbox_record.id,
)