226 lines
12 KiB
Markdown
226 lines
12 KiB
Markdown
# ACP Model, Mode, Registry, and Credential Implementation Plan
|
|
|
|
## Goal
|
|
|
|
Complete Galaxy's ACP integration so that ACP agents can be discovered, configured, selected through the normal model selector, launched with the selected model/configuration, and persisted safely across sessions. Keep all ACP metadata, settings, persistence, selector behavior, runtime protocol handling, and settings UI synchronized without duplicate representations or dead code.
|
|
|
|
## Constraints and invariants
|
|
|
|
- ACP session configuration is represented by the protocol's `configOptions`, not a hard-coded model/mode matrix.
|
|
- Prefer `configOptions` over the legacy `modes` API.
|
|
- Preserve agent-provided option and value ordering.
|
|
- Treat option values as opaque IDs; never parse display labels to reconstruct values.
|
|
- Omitted ACP capabilities mean unsupported.
|
|
- Only send capability-gated request fields when the agent advertises support.
|
|
- Registry metadata describes agents and distributions; it does not provide live model/mode availability.
|
|
- Live model/config discovery comes from the running ACP agent.
|
|
- Keep non-secret ACP metadata in settings/persistence.
|
|
- Keep credentials in secure storage/Keychain; do not put secrets in settings.toml or ACP command arguments.
|
|
- Preserve support for custom ACP agents not present in the registry.
|
|
- Avoid duplicate selector/model representations; use shared normalized ACP types.
|
|
- Do not regress existing Bedrock, OpenAI/LiteLLM, MCP, authentication, or provider behavior.
|
|
|
|
## Shared data model
|
|
|
|
Create or consolidate one normalized ACP data model shared between the ACP crate, settings, persistence, model selector, and settings UI.
|
|
|
|
Required concepts:
|
|
|
|
- `AcpAgentInfo`
|
|
- registry ID
|
|
- display name/title/name
|
|
- description
|
|
- version
|
|
- repository/website
|
|
- authors/license
|
|
- icon URL
|
|
- distribution metadata
|
|
- `AcpAgentCapabilities`
|
|
- load session
|
|
- resume
|
|
- close/delete session
|
|
- additional directories
|
|
- prompt image/audio/embedded context
|
|
- MCP HTTP/SSE
|
|
- boolean config options
|
|
- `AcpConfigOption`
|
|
- option ID
|
|
- name
|
|
- description
|
|
- category
|
|
- type
|
|
- current value
|
|
- ordered values
|
|
- `AcpConfigValue`
|
|
- opaque value ID/value
|
|
- display name
|
|
- description
|
|
- `AcpModelSelection`
|
|
- agent ID
|
|
- complete selected option-value map
|
|
- stable selector ID
|
|
- display labels
|
|
|
|
Use serde-compatible forms for settings and persistence. Keep protocol-native conversion code in the ACP crate or one app adapter module, not duplicated in multiple consumers.
|
|
|
|
## Scope Note
|
|
|
|
The current delivery scope prioritizes the ACP core runtime, live discovery, configuration
|
|
persistence, restoration, and selector propagation. Registry browsing, agent installation, and
|
|
credential migration remain deferred product work and are intentionally not completion blockers for
|
|
this core scope.
|
|
|
|
## Task list
|
|
|
|
### Phase 1: Establish clean shared types
|
|
|
|
- [ ] Inspect current ACP schema exports and app settings/persistence types.
|
|
- [ ] Replace ad hoc `serde_json::Value` use where practical with a shared serializable opaque ACP config value representation.
|
|
- [ ] Add explicit conversion functions between generated ACP schema types and Galaxy settings/persistence types.
|
|
- [ ] Add stable equality/hash/identity helpers for config selections.
|
|
- [ ] Add unit tests for option/value conversion, unknown categories, unknown option types, boolean values, and ordering.
|
|
- [ ] Ensure `AcpConversationData::for_fork` preserves selections while clearing session IDs.
|
|
|
|
### Phase 2: ACP initialization and discovery
|
|
|
|
- [ ] Extend ACP initialization client capabilities to advertise supported boolean config options.
|
|
- [ ] Capture `agentInfo` from `initialize`.
|
|
- [ ] Capture all relevant initialization capabilities.
|
|
- [ ] Add an explicit discovery API on `AcpSessionManager` or a dedicated discovery result path.
|
|
- [ ] Create a temporary discovery session using the configured working directory and appropriate MCP servers.
|
|
- [ ] Read the complete `configOptions` response from `session/new`.
|
|
- [ ] Preserve agent option/value ordering.
|
|
- [ ] Support discovery for custom executables as well as built-in presets.
|
|
- [ ] Close/delete the temporary discovery session when the advertised capability allows it.
|
|
- [ ] Make discovery failures non-destructive: retain last known cache and expose an actionable error.
|
|
- [ ] Add discovery timeout and cancellation handling.
|
|
- [ ] Add tests using fake ACP agents for successful discovery, authentication failure, missing options, malformed options, and timeout.
|
|
|
|
### Phase 3: Runtime config application and updates
|
|
|
|
- [ ] Apply selected values after `session/new` and before the first prompt.
|
|
- [ ] Capture the complete response from `session/set_config_option`.
|
|
- [ ] Replace the current complete config state after every successful set operation.
|
|
- [ ] Convert `config_option_update` notifications into app-visible events.
|
|
- [ ] Reconcile dependent options when changing a model changes modes/thought levels.
|
|
- [ ] Reject or safely drop stale values that are no longer advertised.
|
|
- [ ] Ensure restored sessions reconcile persisted selections with the agent's current config state.
|
|
- [ ] Track current config values in runtime session metadata.
|
|
- [ ] Apply capability checks for load/resume/close/delete/additional directories/MCP transports.
|
|
- [ ] Add tests for setting options, dependent option changes, rejected values, and runtime notifications.
|
|
|
|
### Phase 4: Settings.toml persistence and synchronization
|
|
|
|
- [ ] Finalize the `ai.acp.agents` settings schema.
|
|
- [ ] Persist registry metadata and runtime discovery metadata without credentials.
|
|
- [ ] Persist capabilities and complete config options atomically.
|
|
- [ ] Store discovery timestamp and source/version information.
|
|
- [ ] Invalidate or refresh discovery when launch fingerprint, executable, arguments, preset version, or agent version changes.
|
|
- [ ] Preserve custom launch configuration while refreshing registry metadata.
|
|
- [ ] React to ACP settings changes and refresh the model list.
|
|
- [ ] Handle malformed/stale settings gracefully.
|
|
- [ ] Add settings schema validation and round-trip tests.
|
|
- [ ] Add a documented example to the repository's settings documentation or sample `settings.toml` if one exists.
|
|
|
|
### Phase 5: ACP Registry integration
|
|
|
|
- [ ] Add a registry client for `https://cdn.agentclientprotocol.com/registry/v1/latest/registry.json`.
|
|
- [ ] Parse the registry version and agent entries.
|
|
- [ ] Support npm/npx, uvx, and platform-specific binary distributions.
|
|
- [ ] Select the correct operating system and architecture distribution.
|
|
- [ ] Preserve command, args, environment, archive, checksum, icon, and version metadata.
|
|
- [ ] Validate URLs, commands, arguments, environment names, and checksums before use.
|
|
- [ ] Cache the registry with a refresh timestamp and last-known-good fallback.
|
|
- [ ] Never auto-install or execute an agent without explicit user action.
|
|
- [ ] Preserve custom agents outside the registry.
|
|
- [ ] Add registry parsing/platform-selection/security tests.
|
|
|
|
### Phase 6: Model selector integration
|
|
|
|
- [ ] Add ACP choices through the existing `LLMPreferences`/model selector path.
|
|
- [ ] Use structured selection data instead of parsing encoded display IDs.
|
|
- [ ] Show ACP choices under an ACP agent grouping.
|
|
- [ ] Render model labels such as `GPT 5.4 Sol (Ultra)` while preserving structured values.
|
|
- [ ] Use `model` as the primary selector dimension.
|
|
- [ ] Use `mode` and `thought_level` as secondary labels or grouped choices.
|
|
- [ ] Keep `model_config` and advanced/unknown options in an ACP configuration panel rather than exploding the model list.
|
|
- [ ] Avoid generating invalid Cartesian combinations for dependent options.
|
|
- [ ] Refresh selector choices after discovery or config updates.
|
|
- [ ] Ensure the selected row propagates into `AcpConversationData.config_values`.
|
|
- [ ] Ensure model metadata, transcript metadata, usage metadata, and restored conversations use the selected ACP identity.
|
|
- [ ] Add selector and selection propagation tests.
|
|
|
|
### Phase 7: Agent screen/settings UI
|
|
|
|
- [ ] Extend the ACP settings widget with registry-backed agent selection.
|
|
- [ ] Show agent icon, display name, description, version, and installation status.
|
|
- [ ] Add refresh registry action.
|
|
- [ ] Add discover/refresh capabilities action.
|
|
- [ ] Show discovery status, timestamp, and actionable errors.
|
|
- [ ] Show discovered models/modes and option descriptions.
|
|
- [ ] Show advanced config options without duplicating selector logic.
|
|
- [ ] Add install/configure action only with explicit user confirmation.
|
|
- [ ] Support custom command/args fields and preserve them when switching registry entries.
|
|
- [ ] Use existing button themes and UI components.
|
|
- [ ] Add UI tests or view-model tests for loading, error, refresh, and selection states.
|
|
|
|
### Phase 8: Credentials and secure storage
|
|
|
|
- [ ] Leave global Keychain registration intact.
|
|
- [ ] Audit ACP/OpenAI/LiteLLM credential paths for secrets in settings.toml or command arguments.
|
|
- [ ] Store Galaxy-managed ACP/OpenAI/LiteLLM API keys through the existing secure-storage service.
|
|
- [ ] Keep only non-secret references/configuration in settings.toml.
|
|
- [ ] Add migration from existing plaintext settings keys to secure storage.
|
|
- [ ] Decide and document behavior when secure storage is unavailable.
|
|
- [ ] Do not copy or manage credentials owned by ACP agents themselves.
|
|
- [ ] Add tests for secure-storage read/write/migration/error behavior.
|
|
|
|
### Phase 9: Backend/provider/translators
|
|
|
|
- [ ] Ensure ACP selected configuration flows through request creation, response streaming, persistence, restoration, and fork paths.
|
|
- [ ] Ensure ACP translator model IDs use complete structured selections.
|
|
- [ ] Ensure OpenAI/LiteLLM provider routing remains unchanged.
|
|
- [ ] Ensure Bedrock provider routing remains unchanged.
|
|
- [ ] Ensure no ACP-only assumptions leak into provider translators.
|
|
- [ ] Add integration coverage for OpenCode over LiteLLM.
|
|
- [ ] Verify cancellation, steering, tool calls, usage, and session restore with selected config values.
|
|
|
|
### Phase 10: Validation and cleanup
|
|
|
|
- [ ] Search for duplicate ACP model/config representations and consolidate them.
|
|
- [ ] Remove temporary or dead ACP helper code.
|
|
- [ ] Add exhaustive enum matching where applicable.
|
|
- [ ] Run formatting.
|
|
- [ ] Run targeted ACP/persistence/settings/model tests.
|
|
- [ ] Run workspace checks.
|
|
- [ ] Run nextest.
|
|
- [ ] Run clippy with warnings denied.
|
|
- [ ] Review Cargo.lock changes from `cargo update`.
|
|
- [ ] Review security implications of registry execution and credential migration.
|
|
- [ ] Confirm settings UI, selector, runtime, persistence, registry, and secure storage are synchronized.
|
|
|
|
## Required validation commands
|
|
|
|
```bash
|
|
./script/format
|
|
cargo check --workspace
|
|
cargo nextest run --no-fail-fast --workspace --exclude command-signatures-v2
|
|
cargo clippy --workspace --all-targets --all-features --tests -- -D warnings
|
|
cargo test --doc
|
|
```
|
|
|
|
## Completion criteria
|
|
|
|
The work is complete only when:
|
|
|
|
1. A configured ACP agent can be discovered and its live models/config options are cached.
|
|
2. The normal model selector displays valid ACP model/config choices.
|
|
3. Selecting a choice persists the complete structured configuration.
|
|
4. A new ACP session receives the selected values before prompting.
|
|
5. Dynamic config updates refresh the selector/settings cache.
|
|
6. Restored and forked conversations preserve correct selection behavior.
|
|
7. Registry metadata can configure/install known agents without excluding custom agents.
|
|
8. Credentials use secure storage and are not written to settings.toml.
|
|
9. Existing Bedrock/OpenAI/LiteLLM/MCP/auth behavior remains intact.
|
|
10. Targeted tests, workspace checks, formatting, nextest, and clippy pass.
|