feat(settings): let plugin-registered namespaces opt into the configuration-client exposure boundary

[omnisurge]

Summary

A Host plugin can register a settings namespace via ctx.settings.register(ns, schema) (packages/settings/settings/src/index.ts:426), and the settings seam serves it fully — layering, validation, persistence, settings/document-updated. But the apiproxy settings RPC domain then makes that namespace invisible to and unwritable by configuration clients: describe filters by exposedNamespaces() (packages/host/apiproxy/src/api-proxy.ts:3269), and mutate/update/replace refuse with settings-not-exposed (:2009).

exposedNamespaces() (:1953) is a fixed union of:

1. configurable model providers' settingsNs (ctx.llm.listConfigurableProviders()),
2. a hardcoded WEB_SETTINGS_NAMESPACES list (:126),
3. a hardcoded PRODUCT_SETTINGS_NAMESPACES set (:256).

There is no plugin-reachable seam to join it. The result: a plugin that ships a settings card (via the public settings.plugin.item list slot — the same slot the three built-in cards self-register into) cannot read or write its own namespace through ctx.settingsScope.bind({ namespace }), the exact channel the built-in cards use. describe hides it, so the scope reports unavailable; mutate refuses the write.

Why this matters

The plugin configuration page is explicitly extensible on the UI side (settings.plugin.item, replaceRisk: none in the slot catalog), and the settings seam is explicitly extensible on the storage side (settings.register from any Host plugin). The RPC exposure boundary breaks the chain in the middle: the first two seams advertise a plugin-owned settings card as a supported composition, the third makes it impossible.

Concrete use case: a plugin that routes delegated subagents to a user-chosen provider/model. The route belongs in dsh settings (layered user/base/default, settings.yaml persistence, live apply). Today the plugin must stand up its own loopback HTTP endpoint over ctx.webServer.register and bridge to its owner scope — which works precisely because the owner scope is not fenced — duplicating what settingsScope already does for built-in namespaces.

Proposal

Let namespace registration carry an exposure opt-in, e.g.

ctx.settings.register(ns, schema, { expose: 'configuration-clients' })

and have exposedNamespaces() union in the namespaces whose registrations asked for it, instead of (or in addition to) the hardcoded lists.

Notes on the obvious concerns:

• Default stays closed. No opt-in, no exposure — the current "a future registration does not become remotely readable or writable by default" invariant is preserved.
• Secrets are already handled. Wire views are redacted by the seam (redactSecrets), and secret writes ride the credentials domain; an exposed plugin namespace inherits both.
• Write validation is already the registrant's. Schema + validate option gate every write; exposure adds no new mutation power, it only stops refusing a channel the registrant owns Host-side anyway (the owner scope can update/replace its own namespace today, unfenced — the fence currently only blocks browser-reachable convenience, not Host capability).

Alternatives considered (and why they're worse)

• Plugin-owned loopback endpoint bridging to the owner scope (what we do now): works, but every plugin reinvents transport/auth/validation for a channel the platform already has.
• Hijacking an already-exposed namespace's spare fields: schema validation rightly refuses; also semantically wrong.
• Patching WEB_SETTINGS_NAMESPACES: it's a compiled-in constant, not a config entry — unreachable without forking the host bundle.

Acceptance sketch

• A Host plugin registering settings.register('my-plugin', schema, { expose: ... }) sees its namespace in settings.describe responses and can write it via settings.mutate.
• A plugin client card using ctx.settingsScope.bind({ namespace: 'my-plugin' }) behaves exactly like the built-in cards (ready status, writes land in settings.yaml, settings/document-updated fires).
• A registration without the opt-in remains invisible/refused, as today.

[argszero]

I verified every claim in this proposal against current master (47f9438), and the strongest supporting evidence is one the proposal does not cite: the host itself documents this exact move as deferred work.

1. All cited claims check out

• settings.register at settings/src/index.ts:435 (SettingsRegisterOptions today is base / applies / validate only, :36-62 — no exposure field).
• describe filters by exposedNamespaces() at api-proxy.ts:3264-3269; the scope binder derives status: 'unavailable' purely from the namespace's absence in that filtered view (client/ui-settings/src/client/settings-scope.ts:170-179) — so the RPC filter is the only thing standing between a plugin card and ready.
• settingsWrite refuses with settings-not-exposed at :2009 (mutate/update/replace share that one guard, :2010-2013); the error is tested at api-proxy-config.spec.ts:404,454,564.
• exposedNamespaces() (:1953-1957) = modelProviderNamespaces() (:1943-1944, ctx.llm.listConfigurableProviders() → settingsNs) + WEB_SETTINGS_NAMESPACES (:126-128) + PRODUCT_SETTINGS_NAMESPACES (:256) — exactly the three arms you list.
• The "owner scope is unfenced host-side" claim is also correct: register returns a SettingsScope whose update/replace are seam-level (:457+) with no exposure check; the fence exists only in the apiproxy RPC domain.

2. The maintainers' own note says this is the intended direction

api-proxy.ts:116-124 (the WEB_SETTINGS_NAMESPACES doc comment) reads, verbatim:

"a namespace absent here answers settings-not-exposed even when its owner registered it, so adding a section to that page is a decision made here rather than by the registering plugin. Moving that declaration to settings.register(), so a plugin can expose its own configuration without a change in this package, is deferred work."

So the proposal is not a departure from the design — it is the comment's stated plan. The { expose: 'configuration-clients' } shape with a default-closed invariant is exactly the semantics that comment implies.

3. Implementation shape is small and host-side-only

The cleanest minimal-diff path, following the seam's existing patterns:

• Add expose?: boolean to SettingsRegisterOptions (settings/src/index.ts:36-62); the registration object carries it (:439-450).
• Surface it per-descriptor on SettingsDescriptor (:64-90 — "One registered namespace as surfaced to configuration UIs") so the seam stays the single source of truth; settings.describe() already returns live registrations only.
• In apiproxy, exposedNamespaces() unions in settings.describe() entries whose registration asked for it, alongside the three existing arms. Since settingsWrite (:2009) and describe (:3264) both already hold the settings handle, no new service plumbing is needed.

Blast radius: one option field + one descriptor field + one union arm. The client side needs zero changes — settingsScope.bind is namespace-agnostic by construction; a plugin card using the public settings.plugin.item slot against its own namespace behaves like the built-ins the moment the descriptor appears in the filtered view.

4. A lifecycle advantage over the static allowlist

Registrations are fiber-scoped effects (settings.register's disposer removes the namespace and its observers, :451-456), and duplicate registration throws (:436-437). That means: exposure is owned unambiguously by the registrant, and it auto-revokes on plugin unload — a plugin-exposed namespace can never linger as remotely readable after its owner is gone, which the compiled-in allowlists cannot promise in reverse. Default-closed is preserved by construction: no expose, no descriptor flag, no filter match.

5. Redaction is inherited, verified

Both read paths already pass redactSecrets: true (:2017, :3268) and map secrets into the wire view (:1937); an exposed plugin namespace inherits that with no extra work.

This is also the settings instance of a broader pattern: downstream plugins keep hitting fixed surfaces that the two adjacent seams already advertise as extensible — event-type registration (#1538/#1584) and the tool-subagent agentOptions drop (#1619) being the other two. A "downstream plugin surface" workstream covering all three would give plugin authors one consistent story. For this thread specifically: the proposal is correct, verified, and matches the host's own documented plan — I'd support it as-is.