refactor: centralize runtime feature flag bindings (#2142)
This commit is contained in:
@@ -126,10 +126,8 @@ The launcher starts `agentctl`, performs a one-time nonce handshake, and supplie
|
||||
| `office.jwtSigningKey` | `KANDEV_OFFICE_JWTSIGNINGKEY` | random per start | HMAC key for Office agent-runtime JWTs. Set a stable secret when Office tasks must survive restarts. |
|
||||
| `voice.openAIApiKey` | `KANDEV_VOICE_OPENAI_API_KEY` | empty | Server-side transcription fallback when browser speech recognition is unavailable. Empty disables the fallback and its endpoint returns unavailable. |
|
||||
| `features.office` | `KANDEV_FEATURES_OFFICE` | `false` in production | Experimental Office UI, routes, services, and automation. |
|
||||
| `features.plugins` | `KANDEV_FEATURES_PLUGINS` | `false` in production | Extensible plugin system: install/manage plugins, spawn plugin backends, and load native UI bundles. Loaded plugin code runs with backend privileges. |
|
||||
| `features.app_status_bar` | `KANDEV_FEATURES_APP_STATUS_BAR` | `false` in production | Opt-in global connection/host-metrics/plugin surface: bottom bar on tablet/desktop and Status drawer on phones. Disabling it does not suppress active WebSocket connectivity warnings. |
|
||||
| `features.plugins` | `KANDEV_FEATURES_PLUGINS` | `false` in production | Extensible plugin system: install/manage plugins, spawn plugin backends, and load native UI bundles. Loaded plugin code runs with backend privileges. |
|
||||
| `features.app_status_bar` | `KANDEV_FEATURES_APP_STATUS_BAR` | `false` in production | Opt-in global connection/host-metrics/plugin surface: bottom bar on tablet/desktop and Status drawer on phones. Disabling it does not suppress active WebSocket connectivity warnings. |
|
||||
| `features.auth` | `KANDEV_FEATURES_AUTH` | `false` in production | Opt-in authentication and per-user workspaces. The first visitor after enabling completes setup and becomes the admin. |
|
||||
| `features.claude_background_prompt_handoff` | `KANDEV_FEATURES_CLAUDE_BACKGROUND_PROMPT_HANDOFF` | `false` | High-risk experiment that lets Claude Code accept a new prompt after its foreground yields while adapter-attested background work remains active. Other providers keep the coarse busy gate. |
|
||||
|
||||
Do not infer security from `auth.jwtSecret`: setting it currently does not turn the local server into an authenticated public service. Office's JWT key has a narrower, active purpose. Store both active secrets and third-party API keys in your deployment secret manager; never commit them in `config.yaml`.
|
||||
@@ -291,9 +289,9 @@ voice:
|
||||
|
||||
features:
|
||||
office: false
|
||||
plugins: false
|
||||
app_status_bar: true
|
||||
app_status_bar: true
|
||||
app_status_bar: false
|
||||
auth: false
|
||||
claude_background_prompt_handoff: false
|
||||
```
|
||||
|
||||
Copying this entire file is unnecessary and can freeze old defaults in a deployment. Keep only deliberate overrides. On Windows, do not copy the Unix Docker host/path literals from this example.
|
||||
@@ -307,16 +305,22 @@ Copying this entire file is unnecessary and can freeze old defaults in a deploym
|
||||
| Key | Environment lock | Production default | Effect |
|
||||
|---|---|---|---|
|
||||
| `features.office` | `KANDEV_FEATURES_OFFICE` | off | Experimental autonomous-agent Office surfaces and automation. |
|
||||
| `features.plugins` | `KANDEV_FEATURES_PLUGINS` | off | Extensible plugin system: install/manage plugins and load their backends and native UI bundles. |
|
||||
| `features.appStatusBar` | `KANDEV_FEATURES_APP_STATUS_BAR` | off | Global status bar on tablet/desktop and Status drawer entry on phones. Enabling changes visibility only; urgent WebSocket connectivity warnings remain visible when it is off. |
|
||||
| `features.plugins` | `KANDEV_FEATURES_PLUGINS` | off | Extensible plugin system: install/manage plugins and load their backends and native UI bundles. |
|
||||
| `features.appStatusBar` | `KANDEV_FEATURES_APP_STATUS_BAR` | off | Global status bar on tablet/desktop and Status drawer entry on phones. Enabling changes visibility only; urgent WebSocket connectivity warnings remain visible when it is off. |
|
||||
| `features.auth` | `KANDEV_FEATURES_AUTH` | off | Authentication and per-user workspaces for the whole install. |
|
||||
| `features.claudeBackgroundPromptHandoff` | `KANDEV_FEATURES_CLAUDE_BACKGROUND_PROMPT_HANDOFF` | off | High-risk Claude Code experiment that exposes recognized background-only activity and admits a successor prompt. |
|
||||
| `debug.devMode` | `KANDEV_DEBUG_DEV_MODE` (also locked by explicit legacy/debug-message vars) | off | High-risk diagnostic endpoints and ACP frame logging. |
|
||||
|
||||
UI changes are persisted in the database and require a restart. An explicitly set environment value wins and locks the UI control. Otherwise a database override wins over the embedded profile/default. Resetting a toggle removes its database override.
|
||||
|
||||
The source checkout's `make dev` activates the embedded development profile, which enables Office, debug surfaces, ACP logging, and a mock agent; the App status bar and Claude background prompt handoff remain opt-in. Installed `run`/desktop builds select the safe production profile unless the environment explicitly opts in. E2E mock variables and routes are test-only and must never be enabled on a public deployment.
|
||||
For a risky release feature, keep the flag off in the shipped profiles, enable it
|
||||
only on a selected install through an admin override or explicit environment,
|
||||
restart, and test it there. Promote the `prod` profile default only after the
|
||||
feature is ready for everyone; keep the registry entry as a kill-switch until
|
||||
the rollout is complete, then remove the live flag and move its key and
|
||||
environment variable to the runtime registry's append-only retired identities.
|
||||
Plugins are part of the base product and are not a runtime toggle.
|
||||
|
||||
The source checkout's `make dev` activates the embedded development profile, which enables Office, debug surfaces, ACP logging, and a mock agent; the App status bar, authentication, and Claude background prompt handoff remain opt-in. Installed `run`/desktop builds select the safe production profile unless the environment explicitly opts in. E2E mock variables and routes are test-only and must never be enabled on a public deployment.
|
||||
|
||||
## Credentials and product settings
|
||||
The **Unread Messages** preference in **Settings > General > Task Actions** controls the Slack-style **New** divider in session transcripts. It defaults off for each user, persists with user settings, and takes effect immediately. Enabling it also allows that user's active transcript view to advance the session read cursor.
|
||||
|
||||
@@ -91,9 +91,8 @@ instance and app store.
|
||||
|
||||
Plugins are distributed as a signed-or-unsigned tarball and installed by URL,
|
||||
manual upload, or filesystem sideload/sync — there is no manifest-paste
|
||||
registration step and no credentials to issue. The whole system sits behind
|
||||
the `plugins` feature flag (Settings > System > Feature Toggles), off by
|
||||
default in production. See [Plugins](plugins.md) for the operator-facing
|
||||
registration step and no credentials to issue. Plugins are part of the base
|
||||
product and are not a runtime feature toggle. See [Plugins](plugins.md) for the operator-facing
|
||||
install/operate flow, [Authoring a plugin](plugins-authoring.md) for the
|
||||
build tutorial and SDK reference, and the [Plugin manifest
|
||||
reference](plugins-manifest.md) for the complete `manifest.yaml` schema.
|
||||
@@ -102,7 +101,34 @@ reference](plugins-manifest.md) for the complete `manifest.yaml` schema.
|
||||
|
||||
Create backend ownership and validation before a web form. Web settings require the appropriate domain client/hook, `src/settings-routes.tsx`, page/components, and sidebar or general navigation. Add a global state slice only when multiple surfaces or WebSocket hydration require it.
|
||||
|
||||
Wire runtime feature flags through every enforcement layer in one change. Add the default to `profiles.yaml` and `FeaturesConfig`, register its environment variable and runtime behavior in `internal/runtimeflags/registry.go`, and gate backend construction, handlers, or other call sites. Mirror the field in the frontend feature types, use `useFeature` for client surfaces, and call `notFound()` from the server layout or page when a guessed URL must remain unavailable. Add backend and frontend tests for both states. A flag is incomplete if any layer can expose or execute the feature while it is disabled. Do not turn an internal package or environment variable into a public setting without first defining its compatibility contract and support status.
|
||||
Wire a release toggle through every enforcement layer in one change:
|
||||
|
||||
1. Add a `KANDEV_FEATURES_*` entry to `profiles.yaml` with `prod`, `dev`, and
|
||||
`e2e` set to `false` until the rollout is ready.
|
||||
2. Add the typed `FeaturesConfig` field with explicit `mapstructure` and `json`
|
||||
tags, then add one metadata/read/apply registration in
|
||||
`internal/runtimeflags/registry.go`. The registry owns the binding; do not
|
||||
add a parallel per-flag map or switch.
|
||||
3. Gate backend construction, handlers, HTTP/WS/MCP actions, background jobs,
|
||||
and agent prompt paths at their narrow composition boundary. The disabled
|
||||
path must fail closed before deriving data, writing state, or dispatching
|
||||
work, while existing readable data remains inert.
|
||||
4. Add the field to the frontend `defaultFeatureFlags` declaration, use
|
||||
`useFeature` for client surfaces, and call `notFound()` from the server
|
||||
layout or page when a guessed URL must remain unavailable.
|
||||
5. Add backend and frontend tests for enabled and disabled behavior, including
|
||||
legacy behavior while the flag is off. Shared refactors, migrations, and
|
||||
data reads are not automatically protected by a feature flag.
|
||||
|
||||
For rollout, merge with the flag off, enable it on one install through an
|
||||
admin override or explicit environment and restart, then promote the `prod`
|
||||
default after observation. Remove the live flag only after it is permanent,
|
||||
and move its key and environment variable to the append-only retired identities
|
||||
in `internal/runtimeflags/registry.go`. Never reuse either identity for
|
||||
different behavior. A flag is incomplete if any layer can expose or execute
|
||||
the feature while it is disabled. Do not turn an internal package or
|
||||
environment variable into a public setting without first defining its
|
||||
compatibility contract and support status.
|
||||
|
||||
Workbench changes must preserve task/session/repository selection, dock-layout restoration, reconnect behavior, and the separate mobile layout. Test unavailable dependencies, invalid credentials, save/test failures, keyboard access, and narrow viewports.
|
||||
|
||||
|
||||
Reference in New Issue
Block a user