@deepseek-ai/dsh-client-ui-settings-plugins

---

description: "Plugins settings section for the dsh web client: feature-owned tabs, the configurable host-plane plugin cards, and the settings.plugin.item extension point." kind: "package-reference"

@deepseek-ai/dsh-client-ui-settings-plugins

English | 中文

Summary

The Plugins settings section groups available plugin editors into collapsed flows. Expand a flow, then a card to read its description and edit its controls. Collapsing a flow retains its drafts. Cards write only on save, with every write fenced by the namespace revision the form read. Feature plugins contribute additional pages through settings.plugins.tab.

Table of Contents

• Use this package
• Understand the implementation
• Further Exploration
• Model Experience

---

Use this package

Open the Plugins section in Settings and select the Plugin configuration tab to edit the host-plane plugins this deployment composes. Available cards follow the served settings namespaces and registered card contributions.

What appears here

The tab reads which settings namespaces the Host serves and dispatches one slot key per namespace, so what renders is the intersection of two ledgers: the namespaces a live Host plugin registered, and the cards registered under those keys. A served namespace no card claims renders nothing, and a card whose namespace this deployment does not serve is never dispatched. The empty line waits for the Host's first answer, so an unanswered read never reads as "this deployment configures no plugin".

Editing and saving

Web access groups the search and fetch selectors with their provider settings. Select the route in Web access, then configure its provider; saving provider credentials or capacity does not select that provider. Approval groups the rule-based assessor before the optional model reviewer: the assessor can reject a request but cannot approve it, while an enabled reviewer replaces the human decision for a valid verdict. An undecided review follows its configured reject-or-delegate policy.

A card stages what the user types and writes it only when they save, and a save commits every staged field of the card in one settings mutation, so a Host validator that constrains fields together judges the complete section. Each control renders staged text, so what is on screen is exactly what a save would store; Discard drops the drafts, and a card holding unsaved edits says so on its header even while collapsed. A successful save collapses the card after the read-back confirms the writes; a failed save keeps the card open, reports the failure, and retains the drafts for correction. A reset stages the composed default rather than writing immediately, and a draft the field does not accept blocks the save instead of being dropped. The Host is the only authority on whether a value was accepted.

The Subagent card stages its permission switch and exact model checkboxes together. Enabling requires at least one selected provider route. Saving submits enabled and allowedModels in one mutation fenced by the revision where that draft began; a newer Host revision marks the draft failed instead of restoring a revoked route. Disabling retains the selected routes for later reuse. Available models are grouped by provider, while saved routes absent from the current catalog appear last and remain removable. Provider names and model descriptions stay live directory facts and are not stored, and the card refreshes them after provider changes, settings commits, and reconnects.

The Default model card stages one exact route. Saving submits provider, model, and a clear of reasoningEffort in one mutation fenced by the revision where that draft began, because an effort stored for the previous model does not describe the new one; a newer Host revision marks the draft conflicted instead of writing over it. The route the section already stores stays selectable even once the catalog stops advertising it. A failed directory read offers a retry in place, and both model cards group available routes by provider and list saved-but-unadvertised routes last.

Card actions and single-line fields use shared Button and Input controls. The disclosure identifies its expanded body, which announces when a save is busy. A successful save returns focus from the collapsing form to its disclosure button; focus elsewhere stays where the user placed it. Save and discard actions wrap within narrow cards.

Secret-role fields

A key control starts blank, reports only whether one is configured, and writes through the credentials domain rather than the settings section; a blank draft writes nothing and keeps the stored key. When a save includes settings and credentials, the settings must be accepted before credentials are written. A refused settings change retains both drafts for retry.

---

Understand the implementation

Implementation internals — click to expand

The section is one extension point and one dispatch rule: feature plugins own their cards; the tab pairs served namespaces with registered cards by slot key.

The tab extension point

The section declares settings.plugins.tab, a root list slot whose labels become ordered tabs; a tab stays mounted after its first selection so local drafts and read-only snapshots survive tab switches. The package registers its own configurable contribution, which declares the nested settings.plugin.item slot — keyed on the settings namespace a card edits. A plugin that ships a browser half registers its own card under its own namespace and owns every part of it: chrome, controls, and copy. Tabs follow the contribution's order; web routing precedes provider configuration, approval stages follow their execution order, and other cards retain their served order.

The write path

Saving writes staged fields through the client settings scope, which fences each write or ordered mutation with the namespace revision the draft read, so a form that has drifted from the document is refused rather than overwriting a concurrent change. A field's presence in the raw user layer — not its value — is what marks it overridden; a reset clears that field so it re-inherits the composition layer. Secret-role fields never ride a response; the card re-reads on the forwarded credentials/reference-updated event for the reference it watches.

---

Further Exploration

These pages cover the settings base, the inventory tab, and the durable seams behind the cards.

• ui-settings — the domain base declaring settings.plugins.tab and the settings scope.
• ui-settings-plugin-inventory — the read-only Plugin list tab in the same section.
• settings — the durable user-settings seam and its file provider.
• credentials — the credential-reference seam secret fields write through.
• ui-settings-general — the settings shell hosting this section.

---

Model Experience

None, as the package is a browser-side settings surface that registers no model surface.

KV Cache effect

None; this package neither assembles nor sends a provider request.

Known Limitations and Deferred Work

These boundaries define which plugins appear and how fresh the list is; they are current package contracts.

• Only host-plane plugins appear — a plugin an agent preset mounts carries its configuration inline in that preset's agent.cordis.yml and cannot register a settings namespace at all, so this section lists nothing for it. Editing those values remains the preset editor's job.
• A card still needs a browser bundle — the browser half must be a dsh.client package built in the client module system's lazy-CJS factory format, and the clientBundle preset that emits it lives in ../../../packages/client/tsdown.client.ts rather than a published package, so a plugin outside this repository has to reproduce that build itself.
• The served namespaces re-read on two signals only — the wire announces settings-document commits and connection resets, not registrations, so a namespace whose owner registers after the tab's read joins the list on the next document commit or reconnect.
• The shell card follows the composed executor — the POSIX and PowerShell executor families share the bash namespace because a host composes exactly one of them, so the served schema differs by platform (PowerShell adds pwshPath) even though the card edits the same two fields on both.

Dev Note

Working context for maintainers — click to expand

None.