Plan harness and backend connection configuration for AI providers

[atomantic]

Problem

AI Providers currently represents execution routes as provider records. Unifying matching CLI/TUI cards reduces duplication, but Claude Ollama and OpenCode Ollama still duplicate a backend's model catalog and connection setup. Conversely, a direct Ollama API connection can point to another machine and must remain independently configured.

Current contracts to preserve

• server/lib/aiToolkit/providers.js stores executable provider IDs, model defaults, and activeProvider; saved tasks and fallback policies reference those IDs.
• server/lib/aiToolkit/internal/providerModes.js pairs matching CLI/TUI connections for shared card enablement and catalogs while retaining both executable records.
• server/routes/providers.js publishes both entries, with executionModes metadata used only by the management page.
• client/src/components/ProviderModelSelector.jsx must continue to offer distinct CLI and TUI selections, even when management shows one card.
• Harness arguments, execution consent, timeouts, and selected model defaults can differ by mode and must survive upgrades.

Proposed design to examine

Separate three concepts: a backend connection (location/authentication/catalog), a harness (Claude, OpenCode, Codex, etc.), and an execution mode (CLI/TUI or direct API). Management navigation would offer Harness > Connection > Model and Direct API > Connection > Model. Do not group connections merely by vendor name: local Ollama and a remote Ollama API are separate identities.

Produce a decision document with concrete wire/store schemas and mock flows before implementing another storage rewrite. Compare retaining executable provider records as a compatibility projection against introducing durable connection/harness IDs with explicit legacy-route mappings. Recommend one design with costs, migration ordering, and downgrade behavior. Keep model capabilities and mode eligibility explicit so a context requiring CLI/API cannot silently receive TUI.

Bounded implementation plan

1. Inventory provider IDs across task schedules, CoS, model selectors, fallback chains, orchestration profiles, and peer schemas. Document which settings belong to connection, harness, mode, or per-task selection.
2. Design management flows: add an existing connection to a harness, configure a new direct API connection, select shared models, edit mode overrides, select the system default mode, and launch TUI in Shell. Preserve deep links and accessibility.
3. Define connection identity and explicit linking/unlinking. Automatically share only proven equivalent connections; never infer equivalence from redacted credentials, display names, or matching model lists.
4. Specify upgrade migration with OR-enabled semantics, unioned catalogs, preserved pins/arguments/secrets/default mode, stable legacy selections, and input-gated derived stores without reference seeds. Add version-gated peer payloads only if the wire format changes.
5. Decompose implementation into independent tracker issues once the schema and migration decision is complete.

Acceptance criteria

• Reviewed design includes examples for Claude + Ollama, OpenCode + the same local Ollama, and a separate remote Ollama API.
• ProviderModelSelector still offers separate CLI/TUI route IDs with the appropriate catalog and eligibility.
• No existing saved selection, active mode, fallback reference, custom connection, or model default is silently redirected or lost.
• Enabling/configuring a connection or starting the application makes no AI generation calls.
• Validation plan covers existing-install migration, custom/different endpoints and credentials, missing runtimes, mode-specific failures, and older peer/client compatibility.

This issue is planning for the next stage; it does not authorize merging different harnesses in the current CLI/TUI card unification.