The open-source app everyone uses to manage agents at work
TypeScript acpxagent-orchestrationagent-skillsagentic-aiai-agentsai-engineeringai-governanceai-toolsautonomous-agentsclaudeclaude-codeclaude-skillscodexhermesllmmcpmulti-agentopenclawproject-managementworkflow-automation
feat: support default-hidden experimental settings (#13980)
Devin Foleye2f1a66aa7a2
diff --git a/docs/deploy/environment-variables.md b/docs/deploy/environment-variables.mdindex 286f42f8f6..c21d4f34b3 100644--- a/docs/deploy/environment-variables.md+++ b/docs/deploy/environment-variables.md@@ -100,6 +100,13 @@ Daytona snapshot for future leases.- Any experimental toggle: `instance.experimental.<flagKey>` (e.g.`instance.experimental.enableSmokeLab`) — the card disappears andvalue-changing writes are rejected.+- All current and future experimental toggles: `instance.experimental.*`.+ Add `!instance.experimental.<flagKey>` entries to leave specific controls+ available. The server expands this policy against its own feature catalog,+ so new toggles stay hidden without an environment change. The Experimental+ page remains available. Exceptions only apply to the wildcard; an explicit+ hidden toggle or `instance.experimental` page restriction always wins,+ regardless of entry order. Unknown exceptions are logged and ignored.- Any top-level company settings page: `company.members`, `company.invites`,`company.secrets`, `company.export`, `company.import` — removed from thesettings sidebar, tab bar, and routing (the company General page is the@@ -132,6 +139,24 @@ is identical to earlier releases. Hiding a toggle does not change its value;pair hiding with the desired default where it matters (for general settings,see [Operator setting defaults](#operator-setting-defaults)).+For example, this allows only the Environments control and keeps the Plugins+settings page hidden:++```sh+PAPERCLIP_HIDDEN_SETTINGS='instance.plugins,instance.experimental.*,!instance.experimental.enableEnvironments'+```++`GET /api/health` returns the expanded concrete keys in `hiddenSettings`.+The UI and settings API use the same restrictions. Reads and same-value+echoes remain allowed; changing a hidden value returns+`403 settings_operator_managed`.++Older images that predate wildcard support ignore the wildcard and exceptions.+Keep their explicit hidden-toggle entries during an upgrade, or upgrade all+images before replacing an explicit list. Once every image supports this+syntax, the wildcard and its exceptions are sufficient. A recognized exception+without a wildcard has no effect.+### Operator setting defaults`PAPERCLIP_SETTING_DEFAULTS` takes a JSON object whose fields come from thediff --git a/packages/shared/src/index.ts b/packages/shared/src/index.tsindex d8f4029708..4b7d7c05f1 100644--- a/packages/shared/src/index.ts+++ b/packages/shared/src/index.ts@@ -2675,6 +2675,7 @@ export {type InstanceFeatureKey,} from "./feature-catalog.js";export {+ EXPERIMENTAL_SETTINGS_WILDCARD,HIDEABLE_COMPANY_PAGES,HIDEABLE_COMPANY_SECTIONS,HIDEABLE_GENERAL_SECTIONS,diff --git a/packages/shared/src/settings-visibility-catalog-growth.test.ts b/packages/shared/src/settings-visibility-catalog-growth.test.tsnew file mode 100644index 0000000000..3606f66ed6--- /dev/null+++ b/packages/shared/src/settings-visibility-catalog-growth.test.ts@@ -0,0 +1,17 @@+import { expect, it, vi } from "vitest";++// Model a future Core release without changing the operator's policy.+vi.mock("./feature-catalog.js", async (importOriginal) => {+ const catalog = await importOriginal<typeof import("./feature-catalog.js")>();+ return { ...catalog, INSTANCE_FEATURE_KEYS: [...catalog.INSTANCE_FEATURE_KEYS, "enableFutureFeature"] };+});++import { parseHiddenSettingsList } from "./settings-visibility.js";++it("hides an added catalog feature without an operator configuration change", () => {+ const parsed = parseHiddenSettingsList("instance.plugins,instance.experimental.*,!instance.experimental.enableEnvironments");+ expect(parsed.unknown).toEqual([]);+ expect(parsed.hidden).toContain("instance.experimental.enableFutureFeature");+ expect(parsed.hidden).toContain("instance.plugins");+ expect(parsed.hidden).not.toContain("instance.experimental.enableEnvironments");+});diff --git a/packages/shared/src/settings-visibility.test.ts b/packages/shared/src/settings-visibility.test.tsindex 0a657065fa..709ca672c3 100644--- a/packages/shared/src/settings-visibility.test.ts+++ b/packages/shared/src/settings-visibility.test.ts@@ -49,6 +49,48 @@ describe("hideable setting keys", () => {});describe("parseHiddenSettingsList", () => {+ it("expands the experimental wildcard into concrete keys without hiding the page", () => {+ const parsed = parseHiddenSettingsList("instance.experimental.*");+ expect(parsed).toEqual({ hidden: INSTANCE_FEATURE_KEYS.map(experimentalSettingKey), unknown: [] });+ expect(parsed.hidden).not.toContain("instance.experimental");+ });++ it("allows only named exceptions, independent of order or duplicates", () => {+ const exception = "!instance.experimental.enableEnvironments";+ for (const raw of [`instance.experimental.*, ${exception}, ${exception}`, `${exception},instance.experimental.*`]) {+ const parsed = parseHiddenSettingsList(raw);+ expect(parsed).toEqual({+ hidden: INSTANCE_FEATURE_KEYS.filter((key) => key !== "enableEnvironments").map(experimentalSettingKey),+ unknown: [],+ });+ }+ });++ it("keeps explicit hides and parent page restrictions stronger than exceptions", () => {+ for (const restriction of ["instance.experimental.enableEnvironments", "instance.experimental"]) {+ for (const raw of [+ `instance.experimental.*,!instance.experimental.enableEnvironments,${restriction}`,+ `${restriction},!instance.experimental.enableEnvironments,instance.experimental.*`,+ ]) {+ const { hidden } = parseHiddenSettingsList(raw);+ expect(hidesExperimentalSetting(new Set(hidden), "enableEnvironments")).toBe(true);+ expect(new Set(hidden).size).toBe(hidden.length);+ }+ }+ });++ it("ignores unknown or out-of-scope exceptions without opening any controls", () => {+ const parsed = parseHiddenSettingsList("instance.experimental.*,!instance.experimental.enableTypo,!instance.plugins,!instance.experimental,!instance.experimental.*");+ expect(parsed.hidden).toEqual(INSTANCE_FEATURE_KEYS.map(experimentalSettingKey));+ expect(parsed.unknown).toEqual(["!instance.experimental.enableTypo", "!instance.plugins", "!instance.experimental", "!instance.experimental.*"]);+ });++ it("does not use exceptions to override individual restrictions without a wildcard", () => {+ expect(parseHiddenSettingsList("!instance.experimental.enableEnvironments").hidden).toEqual([]);+ expect(parseHiddenSettingsList("instance.experimental.enableEnvironments,!instance.experimental.enableEnvironments").hidden)+ .toEqual(["instance.experimental.enableEnvironments"]);+ });+it("accepts workspace controls independently of experimental flags", () => {expect(parseHiddenSettingsList("workspaces.isolation")).toEqual({ hidden: ["workspaces.isolation"], unknown: [] });expect(hidesExperimentalSetting(new Set(["workspaces.isolation"]), "enableIsolatedWorkspaces")).toBe(false);diff --git a/packages/shared/src/settings-visibility.ts b/packages/shared/src/settings-visibility.tsindex 3b1e104739..31c99ae80e 100644--- a/packages/shared/src/settings-visibility.ts+++ b/packages/shared/src/settings-visibility.ts@@ -6,7 +6,8 @@ import { INSTANCE_FEATURE_KEYS, type InstanceFeatureKey } from "./feature-catalo* A hosting operator (a managed cloud, an internal shared server) can hide* settings surfaces that do not apply to their deployment by setting the* `PAPERCLIP_HIDDEN_SETTINGS` environment variable to a comma-separated- * list of keys from this registry. Hiding a surface removes it from the UI+ * list of keys from this registry. An experimental wildcard with named+ * exceptions can also hide future controls automatically. Hiding a surface removes it from the UI* (nav, routes, page sections). Surfaces backed by instance-level mutation* routes are also floored with a 403 carrying* `SETTINGS_OPERATOR_MANAGED_ERROR_CODE`: the Access, Plugins, and Adapters@@ -111,7 +112,7 @@ export type HideableSettingKey =| HideableGeneralSection| HideableExperimentalSetting;-/** Every key `PAPERCLIP_HIDDEN_SETTINGS` accepts. */+/** Concrete setting keys; the parser also accepts the experimental wildcard and exceptions. */export const HIDEABLE_SETTING_KEYS: readonly HideableSettingKey[] = [...HIDEABLE_WORKSPACE_SECTIONS,...HIDEABLE_INSTANCE_PAGES,@@ -124,30 +125,50 @@ export const HIDEABLE_SETTING_KEYS: readonly HideableSettingKey[] = [/** Stable 403 code for writes to operator-hidden settings. */export const SETTINGS_OPERATOR_MANAGED_ERROR_CODE = "settings_operator_managed";+/** Hide current and future experimental controls, with optional !key exceptions. */+export const EXPERIMENTAL_SETTINGS_WILDCARD = "instance.experimental.*";+export interface ParsedHiddenSettings {- /** Recognized keys, deduplicated, in input order. */+ /** Concrete keys, deduplicated; wildcard-derived keys follow in catalog order. */hidden: HideableSettingKey[];/** Unrecognized entries, for the caller to warn about. */unknown: string[];}-/** Parse a `PAPERCLIP_HIDDEN_SETTINGS`-style comma-separated list. */+/**+ * Parse operator settings into concrete keys for both the UI and API.+ * `instance.experimental.*` hides every catalog control except entries such as+ * `!instance.experimental.enableEnvironments`. Exceptions only affect the+ * wildcard; an explicit hidden key or hidden parent page always wins.+ */export function parseHiddenSettingsList(raw: string | undefined): ParsedHiddenSettings {const hidden: HideableSettingKey[] = [];const unknown: string[] = [];if (!raw) return { hidden, unknown };const known = new Set<string>(HIDEABLE_SETTING_KEYS);const seen = new Set<string>();+ const exceptions = new Set<string>();+ let hideExperimental = false;for (const part of raw.split(",")) {const key = part.trim();if (!key || seen.has(key)) continue;seen.add(key);- if (known.has(key)) {+ if (key === EXPERIMENTAL_SETTINGS_WILDCARD) {+ hideExperimental = true;+ } else if (key.startsWith("!instance.experimental.") && known.has(key.slice(1))) {+ exceptions.add(key.slice(1));+ } else if (known.has(key)) {hidden.push(key as HideableSettingKey);} else {unknown.push(key);}}+ if (hideExperimental) {+ for (const feature of INSTANCE_FEATURE_KEYS) {+ const key = experimentalSettingKey(feature);+ if (!exceptions.has(key) && !seen.has(key)) hidden.push(key);+ }+ }return { hidden, unknown };}diff --git a/server/src/__tests__/health.test.ts b/server/src/__tests__/health.test.tsindex 1d97f90e0f..1ff6587693 100644--- a/server/src/__tests__/health.test.ts+++ b/server/src/__tests__/health.test.ts@@ -136,6 +136,22 @@ describe("GET /health", () => {expect(Object.prototype.hasOwnProperty.call(res.body, "hiddenSettings")).toBe(false);});+ it("publishes concrete wildcard restrictions to the UI and refreshes changed exceptions", async () => {+ const env = { PAPERCLIP_HIDDEN_SETTINGS: "instance.plugins,instance.experimental.*,!instance.experimental.enableEnvironments" };+ const app = createApp(undefined, testServerInfo, undefined, env);+ const first = await request(app).get("/health");+ expect(first.status).toBe(200);+ expect(first.body.hiddenSettings).toContain("instance.plugins");+ expect(first.body.hiddenSettings).toContain("instance.experimental.enableMemoryConnectors");+ expect(first.body.hiddenSettings).not.toContain("instance.experimental.enableEnvironments");+ expect(first.body.hiddenSettings.some((key: string) => key.includes("*") || key.startsWith("!"))).toBe(false);++ env.PAPERCLIP_HIDDEN_SETTINGS = "instance.experimental.*,!instance.experimental.enableMemoryConnectors";+ const second = await request(app).get("/health");+ expect(second.body.hiddenSettings).toContain("instance.experimental.enableEnvironments");+ expect(second.body.hiddenSettings).not.toContain("instance.experimental.enableMemoryConnectors");+ });+it("returns 200 when the database probe succeeds", async () => {const db = {execute: vi.fn().mockResolvedValue([{ "?column?": 1 }]),diff --git a/server/src/__tests__/instance-settings-routes.test.ts b/server/src/__tests__/instance-settings-routes.test.tsindex 2eb7a0e96a..ca3747c584 100644--- a/server/src/__tests__/instance-settings-routes.test.ts+++ b/server/src/__tests__/instance-settings-routes.test.ts@@ -853,6 +853,40 @@ describe("instance settings routes", () => {expect(mockInstanceSettingsService.updateExperimental).not.toHaveBeenCalled();});+ it("enforces a wildcard allowlist at the API and preserves hidden values", async () => {+ process.env.PAPERCLIP_HIDDEN_SETTINGS =+ "instance.experimental.*,!instance.experimental.enableIsolatedWorkspaces";+ const app = await createApp(adminActor);++ const rejected = await request(app)+ .patch("/api/instance/settings/experimental")+ .send({ enableEnvironments: true, enableIsolatedWorkspaces: true });+ expect(rejected.status).toBe(403);+ expect(rejected.body.details).toMatchObject({ code: "settings_operator_managed" });+ expect(mockInstanceSettingsService.updateExperimental).not.toHaveBeenCalled();++ // Existing full-form clients may echo hidden values without changing them.+ const allowed = await request(app)+ .patch("/api/instance/settings/experimental")+ .send({ enableEnvironments: false, enableIsolatedWorkspaces: true });+ expect(allowed.status).toBe(200);+ expect(mockInstanceSettingsService.updateExperimental).toHaveBeenCalledWith({+ enableEnvironments: false, enableIsolatedWorkspaces: true,+ });+ });++ it("does not let an allowlist exception bypass an explicit API restriction", async () => {+ process.env.PAPERCLIP_HIDDEN_SETTINGS =+ "instance.experimental.*,!instance.experimental.enableEnvironments,instance.experimental.enableEnvironments";+ const app = await createApp(adminActor);+ const res = await request(app)+ .patch("/api/instance/settings/experimental")+ .send({ enableEnvironments: true });+ expect(res.status).toBe(403);+ expect(res.body.details).toMatchObject({ code: "settings_operator_managed" });+ expect(mockInstanceSettingsService.updateExperimental).not.toHaveBeenCalled();+ });+it("allows writes to non-hidden experimental toggles while others are hidden", async () => {process.env.PAPERCLIP_HIDDEN_SETTINGS ="instance.experimental.enableEnvironments,instance.experimental.enableServerInfoDebugView";