[AgentProfile][ts-client] AgentProfile types + client + resolve/materialize types + deriveSwitchPlan

[simonrosenberg]

Phase 3 — typescript-client · typescript-client · size M · Parent epic #3713

Depends on: [agent-server] /api/agent-profiles router + provenance (#3719, #3720)

ts-client is a small, hand-written repo (no codegen). Work is purely additive. Split into 2 PRs only if the diff gets unwieldy.

Context

The client is a thin, hand-written wrapper (no codegen). Hard ordering: author only after the SDK schema + routers are frozen. No MCPProfilesClient is needed — mcp_server_refs is a plain string[] | null field. The ACP provider credential metadata (api_key_env_var, base_url_env_var, file_secrets) is static and goes directly into src/utils/acp.ts — no API call needed.

Scope

1. AgentProfile union + client

• AgentProfile discriminated union (on agent_kind) in src/models/agent-profile.ts:
  • OpenHands variant: { id, name, revision, llm_profile_ref: string, mcp_server_refs: string[] | null, agent, skills, system_message_suffix, condenser, verification, enable_sub_agents, tool_concurrency_limit }
  • ACP variant: { id, name, revision, acp_server, acp_model, acp_session_mode, acp_prompt_timeout, acp_command, acp_args, mcp_server_refs: string[] | null } — no llm_profile_ref, no credential field
  • AgentProfileSummary for lists.
• src/client/agent-profiles-client.ts over /api/agent-profiles (list/get/save/delete/rename/activate/materialize), surfacing 409-on-referenced + 422-dangling-mcp-server-ref errors via HttpError status.
• Typed agent_profile_id on the conversation-create path (CreateConversationPayload is Record<string, unknown> today — additive, no break).

2. ACP provider descriptor extension

• Extend ACPProviderInfo in src/utils/acp.ts with: api_key_env_var?: string, base_url_env_var?: string, file_secrets?: { secret_name: string; filename: string; env_var: string }[]. Populate for each existing provider (claude-code, codex, gemini). This is static metadata — no API call needed, no server endpoint. The canvas ACP authentication section ([AgentProfile][canvas] Provider-driven ACP Authentication section (creds out of the generic Secrets panel) #3728) reads these fields to render the credential form.

3. Resolve/materialize types + deriveSwitchPlan

• Type the materialize response (resolved AgentSettingsConfig union + ref resolved/dangling status + valid verdict) and the LaunchedProfile { id, revision, snapshot } provenance.
• Pure deriveSwitchPlan(snapshot, targetProfile, providerInfo) → current | switch-live(mutableFields) | start-new(reason) | disabled(reason), consuming ACPProviderInfo.supports_runtime_model_switch + the existing switchProfile/switchLLM/switchAcpModel methods (conversation-client.ts:262–283). OpenHands→OpenHands live only if just the LLM differs; ACP→ACP live only if same provider + identity and only acp_model differs and the provider supports it; kind change never live.

Wiring/publish: dedicated clients only. Wire into ConversationManager, export from src/clients.ts + src/index.ts, add api-clients.test.ts coverage. Publishing is tag-driven; canvas re-pins via the usual temp-SHA dance.

Acceptance criteria

• Exported types match the SDK schemas field-for-field; union narrows on agent_kind (both variants have mcp_server_refs: string[] | null).
• ACPProviderInfo has credential metadata fields for all three providers; no hardcoded provider lists in canvas.
• FK error statuses surfaced; deriveSwitchPlan is pure + unit-tested across all ACP providers + OpenHands.
• tsc clean; new clients tested.

[simonrosenberg]

Status — part 2 of 3 done (issue stays open)

Part 2 · ACP provider descriptor extension — done via OpenHands/typescript-client#210 (merged).

Note on scope: the credential descriptor fields this part asked to add (api_key_env_var, base_url_env_var, file_secrets) were already present on ACPProviderInfo — they landed earlier with the registry-mirror PRs typescript-client#173 / #187 / #205, which post-date this issue's text (and the registry moved from src/utils/acp.ts → src/models/acp.ts). So #210's actual contribution was:

• a unit test (src/__tests__/acp-providers.test.ts) locking the credential metadata in for all three providers + getAcpProvider edge cases (the "add a brief unit test" ask), and
• a one-line mirror re-sync — claude-code supports_set_session_model false → true — which fixed the validate-acp-providers drift check that was red on main (SDK flipped it in ACP claude-code initial model selection via session _meta is silently ignored by claude-agent-acp 0.30.0 #3654).

Acceptance criterion "ACPProviderInfo has credential metadata fields for all three providers" is therefore satisfied on main.

Still outstanding:

• Part 1 · AgentProfile union + client — AgentProfile discriminated union (src/models/agent-profile.ts) + AgentProfilesClient over /api/agent-profiles + typed agent_profile_id on conversation-create. (Prior attempt typescript-client#195 was closed unmerged.)
• Part 3 · resolve/materialize types + deriveSwitchPlan — typed materialize response (resolved AgentSettingsConfig union + LaunchedProfile provenance) and the pure deriveSwitchPlan(snapshot, targetProfile, providerInfo).

Leaving this open to track parts 1 & 3.