Make Codex and Claude Code subscriptions go further: a local model router that gives routine agent work to economical models and keeps your strongest model for the hard parts.
Agent settings feature
This feature presents supported Agent model routing, task collaboration and independent management Skills. It translates an editable draft into the existing Agent settings intent; it does not discover installations, read credentials, authorize a route, or implement file recovery. The code map connects these boundaries to their production owners and executable contracts.
Responsibilities and state
| Entry | Responsibility |
|---|---|
| types.ts | WebView projections and current serialized model choices. These describe the existing native/API contract, not a second capability authority. |
| status.ts | Reads the shared model/collaboration-only status union. A missing model capability is distinct from an unconfigured model or an unreadable status. |
| discovery.ts, AgentDiscoveryFeedback.tsx | Supported catalog, remembered non-secret target hints, common rescan and distinct undiscovered/unavailable states. Backend revalidation owns context and write authority. |
| AgentSkillDetails.tsx | Backend-supplied Skill scope, shared/borrowed availability, unobserved native loading and the existing CLI-entry preparation commands. |
| ecosystems.ts | Explicit current Agent identity, display name, brand and surface labels. Unknown discovered identities have no settings editor. |
| editor-state.ts | Draft initialization, dirty comparison and local form completeness. Only a trusted first connection can preselect a sole enabled route. Existing mappings, including unavailable choices, are retained. |
| settings-request.ts | Ecosystem-specific intent construction, independent model/management/collaboration restore intents, token changes that retain the saved selection, and capability-based prerequisite check selection. |
| AgentModelEditor.tsx | Explicit composition of Codex, Claude and supplementary route forms and their saved-selection summary. Codex allowlist/default/native retention, Claude preset mappings and supplementary routes remain different concepts. |
| AgentSettingsFeedback.tsx | Presentation of authoritative Preview blockers. |
| HermesModelEditor.tsx, HermesRootFields.tsx | One Plan/protocol and explicit effective profile; root fields are shared with source scan. Automatic adapter preparation and unobserved native loading stay distinct. |
| collaboration-check-feedback.ts | Versioned collaboration-check failures become safe login, Skill recovery and retry guidance; native output is never display text. |
| CodexAccessPanel.tsx | Profile/root facts, mode controls, launch commands, visible mode-specific session-history and original-entry guidance, ordinary file-conflict diagnosis and an existing pending Operation's recovery entry. |
| codex-launch.ts, codex-surfaces.ts | Confirmed command-copy eligibility and the distinction between detected executables and mode applicability. |
| mutation-feedback.ts | Submitted, pre-apply cancelled and uncertain outcomes; truthful disable/recovery messages. |
| Agents page | Snapshot refresh, selected Agent/tab, in-memory draft and mode, discard guard, native calls, Operation handoff, confirmation-dependent copy effect and task-history composition. |
Qoder, Pi, DSH and OpenCode share the additional-route editor and explicitly selected Plan IDs
through qoder_additional, pi_additional, dsh_additional and opencode_additional. It does not
edit the native default or show native catalogs, fixed-source choices or import controls.
Hermes selects one default main-model Plan. Its management Skill has independent
prepare/restore controls and needs no model connection or published Plan. Model
restore retains that Skill. Pending model/Skill Operations use the shared exact
retry entry. Statically known channel models are shown separately from unobserved
live session selection. Hermes can independently prepare the shared collaboration
Skill and either existing trigger mode, retaining its native model and requiring
no model plugin. It is not a Worker executor.
All six supported Agents remain in the common catalog even when discovery returns
no usable installation/configuration. Common rescan preserves existing entries;
absence is not proof of uninstallation. Hermes appears before a profile is selected. This
presentation entry has no context or settings authority. Its details contain the
configuration-directory control, reusing HermesRootFields and agent_snapshot
for a selected target; successful discovery replaces the unscoped entry. Existing
backend profiles remain authoritative. A successful selected target is saved as a
Desktop preference and reread after remount/restart; an unavailable remembered
target retains its scope instead of silently selecting a default. Preference
storage failure keeps this session usable and reports that the choice was not saved.
Directory reads, cancellation and failures
never configure routing, prepare resources or imply that Hermes is installed.
With no explicit target, the Desktop host checks its caller's nonempty
HERMES_HOME, otherwise HOME/.hermes, and sends an existing profile through that
same backend scan. It does not guess an IM process's profile. An unavailable
explicit root never falls back to another; an unreadable default remains visible
without hiding other Agents. Known invalid paths, missing explicit roots/configuration
and read errors remain distinct. Hermes uses its own bundled mark in the common icon component.
Management is a separate enable/disable control for every supported family. It
uses the same settings Preview/Apply/owned restore as the other facets, with no
Plan or model requirement. Scope/shared/external facts come from backend status;
retained native files are not presented as globally disabled. CLI entry installation
uses the existing host command only after an explicit click. Current clients opt
into extended Skill status with include_skills; legacy queries retain their
original response shape and primary restore references.
Qoder's editor explains that the selected Qoder CLI must complete its own /login
before using these routes. Saving configuration does not perform native sign-in or
make a model call. A valid native login rejection in the separate Qoder Live check
remains a failed surface result with LIVE_NATIVE_LOGIN_REQUIRED; other native
business errors use LIVE_CLIENT_FAILED, while malformed output remains distinct.
Its model configuration uses the existing Preview, protected token and independent
restore flow. A model restore keeps the collaboration Skill; a collaboration restore
keeps the model routes. Token updates retain the saved ecosystem-specific selection.
Task collaboration remains independently usable without any model connection or
published Plan: its form submits model: keep. DSH configures the standard Web profile model picker; global provider shadowing is
reported by the backend before Apply. Each selected Plan has its own provider and
user-selected Responses/Messages protocol. OpenCode uses its saved native model picker;
its native default and small-model choices remain independent. Relevant native references
are backend Preview facts: removing a referenced selector retains the draft and explains
how to change that reference before restoring.
Both model-capable status and actual
collaboration-only status retain this path. Capability and installed-Skill checks
provide scoped prerequisite or diagnostic facts; neither proves a delegated task
completed or a model route worked. They do not create another settings workflow.
Context IDs bind requests and are not user-facing configuration scopes. Show only
readable locations already supplied by the native projection (native configuration and Skill directories/files); do not infer a path from an opaque context ID.
The Plan editor owns its single-CLI installation selection through
WorkerDependencies; qoder and qodercli paths are presented
as returned by discovery, without adapter or Node placeholders. OpenCode also selects
only its native executable. Its Worker format prerequisite is separate from ordinary
model configuration and collaboration capability; installation guidance names the
supported official package without adding a setup wizard.
The page owns interaction state so changing forms does not create another submission or
Operation store. The native session owns confirmation, protected token registration and
submission identity; the daemon owns persistent Operations, authorization, journals and
recovery. The top-level agents.tsx type exports and agent-editor-state.ts /
agent-mutation-feedback.ts exports remain compatibility entry points for existing callers.
New Agent feature code imports its local owners directly.
Current call paths
- The page invokes
agent_snapshot. The native bridge and Agent session use Client Core to readScanAgents,GetAgentConnectionStatusand the plan catalog. A per-Agent status error stays unknown; discovering an executable does not prove model access. - Enable/Edit creates a draft.
agentSettingsSpecbuilds the current settings intent;preview_agent_settingsreaches native Preview, confirmation and protected Apply. If authoritative blockers require a local check, the page invokescheck_agent_authenticationand re-previews. The form's completeness check cannot authorize a route or prove a live model call. - A returned Operation goes to the shell's existing Operation observer. Missing identity after a possible submission remains uncertain. First Codex profile enable copies a command only after the same Operation succeeds and a fresh snapshot confirms the target. Clipboard failure preserves the completed connection and manual-copy entry; it never replays Apply.
- Ordinary Disable submits a new restore intent through Preview. The backend restores
files conditionally before withdrawing access. A normal file conflict preserves the
original connection and permits a fresh Preview/Operation after repair. The separate
retry_agent_settingsentry is for an existing pending Operation, including historical sealed revoke tails; it is not the ordinary conflict retry path.
The native check session separately owns exact ecosystem/surface checks, paid-call consent and response validation for real-call diagnostics. These backend checks and their acceptance evidence are not additional enable/save steps or model-verification badges on the settings page.
Keep the product capabilities separate
| User capability | Owner and evidence boundary |
|---|---|
| Scan installations / read connection state | Native Agent snapshot and backend integrations; this feature renders the projection. |
| Import an Agent's existing model source into HiRoute | Model management, device scan and the protected candidate flow. Import does not configure that Agent to use HiRoute. |
| Connect an Agent to HiRoute routing | These forms and settings intents, followed by native/backend Preview and Apply. |
| Safely restore managed configuration | Application transaction and integration/storage effects. The UI presents progress and recovery actions; it cannot infer safety from file appearance. |
| Copy a command / start an Agent | Copy is a host clipboard effect. It does not launch a process, enable service startup or prove a model call. Existing Codex profile/root applicability stays explicit. |
| Enable delegation / execute a Worker task | Collaboration configures the caller's task-routing skill. Task history and Worker contracts separately own execution, cancellation and results. Model routing support does not imply Worker harness support. |
Product contract tests
| User journey or invariant | Representative evidence |
|---|---|
| Shared configuration actions and state across the supported Agent ecosystems, without an automatic live model call | agent.configuration.shared-interactions in the Agent browser scenarios |
| First enable, exact existing selections, unknown state and discard protection | agent-editor-state.test.mjs |
| Correct ecosystem intent, independent restores, saved-selection token rotation and unsupported identity rejection | agent-settings-request.test.mjs |
| Collaboration without a model or published Plan, prerequisite failure/retry and restore; independent single-CLI selection | qoder.collaboration.enable-without-model, qoder.collaboration.retry-and-restore, qoder.installation.single-cli in the browser scenarios; status projection |
| Additional routes, cancelled drafts, unavailable saved routes, token rotation and independent restores | qoder.routing.additional-plans, qoder.routing.adjust-and-restore, opencode.routing.additional-plans, opencode.routing.default-in-use; the native settings session and check session retain protected-boundary tests. Browser IPC does not prove native settings preservation or real provider calls. |
| OpenCode native-only installation selection and independent saved Harness choices | opencode.installation.single-cli in the routing browser scenarios. |
| Submission uncertainty and restore-first feedback | agent-mutation-feedback.test.mjs |
| Same successful Operation and fresh target before copying; discovery versus applicability | codex-launch.test.mjs, codex-surfaces.test.mjs |
| Reachable forms, cancellation, mappings and native clipboard IPC selection | Agent browser scenarios, clipboard.test.mjs |
| File conflict keeps the grant, service-failure compensation and delete races | backend profile tests |
| Historical sealed-tail restart and same-Operation recovery | legacy recovery tests |
Pure Node tests prove draft/intent contracts. Browser scenarios exercise components with mock IPC; backend fixtures prove their specific transaction invariants. None alone proves real Tauri, installed-Agent or account behavior. Select checks using the repository's test planner, retaining that distinction.
Adding an actual ecosystem
Start with the existing enable, adjust, disable and failure-recovery interaction. The scenarios above document those product rules. During review, compare the new ecosystem with Codex and Claude Code: an extra check action, status badge or confirmation needs a product requirement, not just a callable native API. Necessary checks use the authoritative Preview/prerequisite path above; normal configuration does not automatically call a paid model.
First establish its real scan/read/import/connect/restore/launch/delegation capabilities
and the native/backend contract. Add an explicit identity in ecosystems.ts, its DTO and
draft/intent cases, and any required blocker presentation. Add a dedicated form through
AgentModelEditor only when model management is supported; collaboration-only status
must not acquire an empty model form. Unknown identities must not borrow Claude settings or an existing launch
command. Keep the common page's submission/Operation flow unless the new behavior needs
an independently designed contract.
Use a user journey to decide what can be shared after the first real integration. This feature has no universal plugin protocol or dynamic form schema, and does not claim support for additional ecosystems. New native commands, Worker harnesses, configuration formats or recovery semantics require their own contract work rather than a new UI label.
Acceptance feedback
Settings Preview blockers remain authoritative. Show the missing capability and an actionable next step for configuration conflicts, unsafe write targets, and native authentication checks; do not collapse distinct blockers into repeated generic text.