agent-relay-server 0.60.1 → 0.61.1

package/src/security.ts

@@ -5,6 +5,7 @@ import { dirname, join, resolve } from "node:path";
 import { getDb } from "./db";
 import { isPathWithinBase } from "./utils";
 import type { ComponentToken, TokenConstraints } from "./types";
+import { hasScope, normalizeScope } from "agent-relay-sdk/types";
 
 const LOOPBACK_HOSTS = new Set(["127.0.0.1", "::1", "localhost"]);
 
@@ -99,30 +100,7 @@ type AuthorizationCheck = {
   resource?: AuthorizationResource;
 };
 
-const SCOPE_ALIASES: Record<string, string> = {
-  "admin:*": "system:admin",
-  "system:write": "system:admin",
-  "agents:read": "agent:read",
-  "agents:write": "agent:write",
-  "messages:read": "message:read",
-  "messages:write": "message:send",
-  "tasks:read": "task:read",
-  "tasks:write": "task:write",
-  "commands:read": "command:read",
-  "commands:write": "command:write",
-  "channels:read": "channel:read",
-  "channels:write": "channel:write",
-  "integrations:read": "integration:read",
-  "integrations:write": "integration:write",
-  "connectors:read": "integration:read",
-  "connectors:write": "integration:write",
-  "events:create": "integration:write",
-  "tasks:create": "task:write",
-};
-
-export function normalizeScope(scope: string): string {
-  return SCOPE_ALIASES[scope] ?? scope;
-}
+export { normalizeScope };
 
 export function getIntegrationAuth(req: Request): IntegrationAuth | null {
   const token = extractToken(req);
@@ -170,6 +148,8 @@ export function requiredScopeFor(method: string, pathname: string): string | nul
   if (pathname === "/api/orchestrators/bootstrap") return "token:write";
   if (pathname.match(/^\/api\/orchestrators\/[^/]+\/logs\//)) return "logs:read";
   if (pathname.match(/^\/api\/orchestrators\/[^/]+\/terminal\//)) return "terminal:attach";
+  const settingScope = requiredSettingsScopeFor(method, pathname);
+  if (settingScope !== undefined) return settingScope;
   if (pathname.startsWith("/api/artifacts")) {
     if (method === "GET" || method === "HEAD") return "artifact:read";
     if (method === "DELETE") return "artifact:admin";
@@ -201,6 +181,7 @@ export function requiredScopeFor(method: string, pathname: string): string | nul
   if (pathname.startsWith("/api/recipes")) return method === "GET" ? "recipes:read" : "recipes:write";
   if (pathname === "/api/runtime-tokens/renew") return "agent:write";
   if (pathname.startsWith("/api/runtime-tokens")) return "token:write";
+  if (pathname === "/api/tokens/me") return null;
   if (pathname.startsWith("/api/tokens") || pathname.startsWith("/api/token-profiles")) return method === "GET" ? "token:read" : "token:write";
   if (pathname.startsWith("/api/maintenance")) return "system:admin";
   if (pathname.startsWith("/api/tasks")) return method === "GET" ? "task:read" : "task:write";
@@ -251,12 +232,15 @@ export function requiredComponentScopeFor(method: string, pathname: string): str
   if (pathname === "/api/mcp") return "mcp:use";
   if (pathname.match(/^\/api\/orchestrators\/[^/]+\/logs\//)) return "logs:read";
   if (pathname.match(/^\/api\/orchestrators\/[^/]+\/terminal\//)) return "terminal:attach";
+  const settingScope = requiredSettingsScopeFor(method, pathname);
+  if (settingScope !== undefined) return settingScope ?? "system:admin";
   if (pathname.startsWith("/api/commands")) {
     if (method === "GET") return "command:read";
     return "command:write";
   }
   if (pathname.startsWith("/api/merges")) return method === "GET" ? "command:read" : "command:write";
   if (pathname.startsWith("/api/workspaces")) return method === "GET" ? "agent:read" : "agent:write";
+  if (pathname === "/api/tokens/me") return null;
   if (pathname.startsWith("/api/tokens") || pathname.startsWith("/api/token-profiles")) return method === "GET" ? "token:read" : "token:write";
   if (pathname.startsWith("/api/maintenance")) return "system:admin";
   if (pathname === "/api/recipes/start") return "recipe:start";
@@ -298,6 +282,32 @@ export function requiredComponentScopeFor(method: string, pathname: string): str
   return "system:admin";
 }
 
+const CONFIG_SETTINGS_NAMESPACES = new Set(["steward", "insights", "notifications", "workspace", "landing", "provider"]);
+
+function requiredSettingsScopeFor(method: string, pathname: string): string | null | undefined {
+  if (pathname === "/api/settings") return method === "GET" ? "settings:read" : null;
+  const settingsMatch = pathname.match(/^\/api\/settings\/([^/]+)(?:\/[^/]+)?$/);
+  if (settingsMatch) return settingsScope(method, decodeURIComponent(settingsMatch[1]!));
+  if (pathname === "/api/steward-config") return settingsScope(method, "steward");
+  if (pathname === "/api/workspace-config") return settingsScope(method, "workspace");
+  if (pathname === "/api/insights/config") return settingsScope(method, "insights");
+  const configMatch = pathname.match(/^\/api\/config\/([^/]+)(?:\/[^/]+)?(?:\/history)?$/);
+  if (configMatch) {
+    const namespace = decodeURIComponent(configMatch[1]!);
+    if (CONFIG_SETTINGS_NAMESPACES.has(namespace)) return settingsScope(method, namespace);
+  }
+  if (pathname.match(/^\/api\/providers\/[^/]+\/models\/[^/]+$/) && ["PUT", "PATCH", "DELETE"].includes(method)) {
+    return "settings:write:provider";
+  }
+  return undefined;
+}
+
+function settingsScope(method: string, namespace: string): string | null {
+  if (method === "GET" || method === "HEAD") return `settings:read:${namespace}`;
+  if (["PUT", "PATCH", "POST", "DELETE"].includes(method)) return `settings:write:${namespace}`;
+  return null;
+}
+
 export function signComponentToken(payload: Omit<ComponentToken, "iat"> & { iat?: number }): string {
   const header = { alg: "HS256", typ: "JWT" };
   const body: ComponentToken = {
@@ -404,19 +414,6 @@ function isComponentToken(value: unknown): value is ComponentToken {
     (record.jti === undefined || typeof record.jti === "string");
 }
 
-function hasScope(scopes: string[], requiredScope: string): boolean {
-  const required = normalizeScope(requiredScope);
-  if (scopes.includes("*")) return true;
-  for (const rawScope of scopes) {
-    const scope = normalizeScope(rawScope);
-    if (scope === "system:admin") return true;
-    if (scope === required) return true;
-    const [category] = required.split(":");
-    if (category && scope === `${category}:*`) return true;
-  }
-  return false;
-}
-
 /** Authoritative parent lineage from a registering token's signed constraints — agent-initiated
  * spawn (`spawnedBy`) or the delegating-component path (`parentAgents`). One home, used by both the
  * HTTP `postAgent` route and the bus register path so `spawned_by` is set however a child registers

package/src/settings/modules.ts

@@ -0,0 +1,149 @@
+import {
+  SPAWN_PROVIDERS,
+  errMessage,
+  isRecord,
+  type ConnectorManifest,
+  type JSONSchema,
+  type SettingDescriptor,
+  type SettingDisplay,
+  type SettingScope,
+  type SettingTier,
+} from "agent-relay-sdk";
+import { ValidationError } from "../db";
+import { cleanString } from "../validation";
+import type { ProviderConfig } from "../../runner/src/adapter";
+import { defaultProviderConfig } from "../../runner/src/config";
+import { SETTING_ADMIN_SCOPE, getSettingDescriptor, registerProviderConfigSetting, registerSetting, validateSettingValue } from "./registry";
+
+export const CONNECTOR_CONFIG_NAMESPACE = "connector-config";
+export const CHANNEL_TYPE_CONFIG_NAMESPACE = "channel-type";
+
+export function registerConnectorConfigSetting(
+  manifest: Pick<ConnectorManifest, "id" | "displayName" | "description" | "configSchema">,
+  opts: { defaults?: unknown } = {},
+): SettingDescriptor | undefined {
+  if (!manifest.configSchema) return undefined;
+  const schema = schemaFromRecord(manifest.configSchema, `connector ${manifest.id} configSchema`);
+  return registerModuleSetting({
+    namespace: CONNECTOR_CONFIG_NAMESPACE,
+    key: manifest.id,
+    schema,
+    defaults: opts.defaults ?? schemaDefault(schema) ?? {},
+    scope: { read: "integration:read", write: SETTING_ADMIN_SCOPE },
+    tier: "server-runtime",
+    display: {
+      group: "Connectors",
+      label: manifest.displayName || manifest.id,
+      description: manifest.description ?? `Configuration for connector ${manifest.id}.`,
+      order: 100,
+    },
+  });
+}
+
+export function validateConnectorConfig(manifest: ConnectorManifest, config: unknown): void {
+  const descriptor = getSettingDescriptor(CONNECTOR_CONFIG_NAMESPACE, manifest.id) ?? registerConnectorConfigSetting(manifest);
+  if (!descriptor) return;
+  const validation = validateSettingValue(descriptor.namespace, descriptor.key, config);
+  if (!validation.valid) throw new ValidationError(validation.errors.join("; "));
+}
+
+export function registerChannelTypeSetting(input: {
+  type: string;
+  schema: JSONSchema;
+  defaults: unknown;
+  scope?: Partial<SettingScope>;
+  tier?: SettingTier;
+  display?: Partial<SettingDisplay>;
+}): SettingDescriptor {
+  const type = cleanString(input.type, "channel type", { required: true, max: 80 })!;
+  return registerModuleSetting({
+    namespace: CHANNEL_TYPE_CONFIG_NAMESPACE,
+    key: type,
+    schema: input.schema,
+    defaults: input.defaults,
+    scope: { read: "integration:read", write: SETTING_ADMIN_SCOPE, ...input.scope },
+    tier: input.tier ?? "server-runtime",
+    display: {
+      group: "Channels",
+      label: `${type} channel`,
+      description: `Configuration for ${type} channel integrations.`,
+      order: 120,
+      ...input.display,
+    },
+  });
+}
+
+export interface ProviderSettingsDeclaration {
+  provider: string;
+  defaults: ProviderConfig;
+  display?: Partial<SettingDisplay>;
+}
+
+const providerSettingsDeclarations = new Map<string, ProviderSettingsDeclaration>();
+let builtInProvidersSeeded = false;
+
+export function registerProviderSettingsDeclaration(input: {
+  provider: string;
+  defaults?: ProviderConfig;
+  display?: Partial<SettingDisplay>;
+}): ProviderSettingsDeclaration {
+  const provider = cleanString(input.provider, "provider", { required: true, max: 80 })!;
+  const declaration: ProviderSettingsDeclaration = {
+    provider,
+    defaults: input.defaults ?? defaultProviderConfig(provider),
+    display: input.display,
+  };
+  providerSettingsDeclarations.set(provider, declaration);
+  return declaration;
+}
+
+export function listProviderSettingsDeclarations(): ProviderSettingsDeclaration[] {
+  ensureBuiltInProviderSettingsDeclarations();
+  return [...providerSettingsDeclarations.values()];
+}
+
+export function getProviderSettingsDeclaration(provider: string): ProviderSettingsDeclaration | undefined {
+  ensureBuiltInProviderSettingsDeclarations();
+  return providerSettingsDeclarations.get(provider);
+}
+
+export function providerConfigDefaults(provider: string): ProviderConfig {
+  return getProviderSettingsDeclaration(provider)?.defaults ?? defaultProviderConfig(provider);
+}
+
+export function registerDeclaredProviderConfigSetting(input: { host: string; provider: string }): SettingDescriptor {
+  const declaration = getProviderSettingsDeclaration(input.provider);
+  if (!declaration) throw new ValidationError(`provider must be one of: ${listProviderSettingsDeclarations().map((d) => d.provider).join(", ")}`);
+  return registerProviderConfigSetting({
+    host: input.host,
+    provider: declaration.provider,
+    defaults: declaration.defaults,
+    display: declaration.display,
+  });
+}
+
+function ensureBuiltInProviderSettingsDeclarations(): void {
+  if (builtInProvidersSeeded) return;
+  builtInProvidersSeeded = true;
+  for (const provider of SPAWN_PROVIDERS) {
+    registerProviderSettingsDeclaration({ provider, defaults: defaultProviderConfig(provider) });
+  }
+}
+
+function registerModuleSetting(input: Parameters<typeof registerSetting>[0]): SettingDescriptor {
+  try {
+    return registerSetting(input);
+  } catch (error) {
+    if (error instanceof ValidationError) throw error;
+    throw new ValidationError(errMessage(error));
+  }
+}
+
+function schemaFromRecord(value: Record<string, unknown>, field: string): JSONSchema {
+  if (!isRecord(value)) throw new ValidationError(`${field} must be an object`);
+  return value as JSONSchema;
+}
+
+function schemaDefault(schema: JSONSchema): unknown {
+  return Object.prototype.hasOwnProperty.call(schema, "default") ? schema.default : undefined;
+}

package/src/settings/registry.ts

@@ -0,0 +1,397 @@
+// Settings descriptor registry (epic #380, #382) — the single server-side source
+// of truth for which settings exist, their JSON Schema, defaults, required scope,
+// tier, and display. This is the *declaration* layer over the existing `config`
+// table (src/config-store.ts owns storage + history + the `config.changed` SSE) —
+// it does NOT touch storage. The API (#383), scope enforcement (#385), module
+// wiring (#386), and the Settings UI (#384) all build on this contract.
+//
+// DECISION LOCKED (#380 thread): validation is via `ajv`, descriptors carry full
+// JSON Schema. Each descriptor's schema is ajv-compiled at registration, which
+// validates it against the JSON Schema meta-schema and throws on a malformed
+// schema — fail fast, never seed a broken descriptor.
+//
+// The `SettingDescriptor`/`JSONSchema` types live in `sdk/src/types.ts` (imported
+// here, never re-declared — DRY rule). Keep this module under the ratchet ceiling;
+// add per-surface seed helpers, don't inline a god-object.
+
+import Ajv from "ajv";
+import type { ValidateFunction } from "ajv";
+import {
+  APPROVAL_MODES,
+  errMessage,
+  SPAWN_PROVIDERS,
+  VALID_EFFORTS,
+  type JSONSchema,
+  type SettingDescriptor,
+  type SettingScope,
+} from "agent-relay-sdk";
+
+/** Fail-closed default scope — a descriptor that omits scope requires admin to
+ *  read and write (#385 owns the scope grammar; this layer only declares it). */
+export const SETTING_ADMIN_SCOPE = "system:admin";
+
+// One shared compiler. `strict: false` relaxes ajv's opinionated strict-mode
+// warnings (unknown keywords/formats) so any reasonable JSON Schema compiles,
+// while meta-schema validation (default on) still rejects a structurally broken
+// schema. `allErrors` so value-validation reports every failure, not just the first.
+const ajv = new Ajv({ allErrors: true, strict: false });
+
+/**
+ * Registration input: a descriptor with an optional, possibly-partial `scope`.
+ * The registry resolves any omitted read/write scope to the fail-closed admin
+ * default and returns a fully-populated `SettingDescriptor`.
+ */
+export type SettingRegistration<T = unknown> = Omit<SettingDescriptor<T>, "scope"> & {
+  scope?: Partial<SettingScope>;
+};
+
+interface RegisteredSetting {
+  descriptor: SettingDescriptor;
+  validate: ValidateFunction;
+}
+
+const registry = new Map<string, RegisteredSetting>();
+
+function descriptorId(namespace: string, key: string): string {
+  return `${namespace}:${key}`;
+}
+
+function resolveScope(scope: Partial<SettingScope> | undefined): SettingScope {
+  return {
+    read: scope?.read ?? SETTING_ADMIN_SCOPE,
+    write: scope?.write ?? SETTING_ADMIN_SCOPE,
+  };
+}
+
+/**
+ * Register (or replace) a setting descriptor. Compiles `schema` with ajv — a
+ * malformed JSON Schema throws here, at registration/seed time. The mechanism
+ * #386 modules call to contribute their own settings.
+ */
+export function registerSetting<T>(reg: SettingRegistration<T>): SettingDescriptor<T> {
+  if (!reg.namespace) throw new Error("setting descriptor requires a non-empty namespace");
+  if (!reg.key) throw new Error("setting descriptor requires a non-empty key");
+  const id = descriptorId(reg.namespace, reg.key);
+
+  let validate: ValidateFunction;
+  try {
+    validate = ajv.compile(reg.schema as object);
+  } catch (error) {
+    throw new Error(`invalid JSON Schema for setting "${id}": ${errMessage(error)}`);
+  }
+
+  const descriptor: SettingDescriptor<T> = {
+    namespace: reg.namespace,
+    key: reg.key,
+    schema: reg.schema,
+    defaults: reg.defaults,
+    scope: resolveScope(reg.scope),
+    tier: reg.tier,
+    display: reg.display,
+  };
+  registry.set(id, { descriptor: descriptor as SettingDescriptor, validate });
+  return descriptor;
+}
+
+/** Look up a single descriptor by its (namespace, key) address. */
+export function getSettingDescriptor(namespace: string, key: string): SettingDescriptor | undefined {
+  return registry.get(descriptorId(namespace, key))?.descriptor;
+}
+
+/** All registered descriptors (built-ins + module contributions), seeded on first access. */
+export function listSettingDescriptors(): SettingDescriptor[] {
+  ensureSeeded();
+  return [...registry.values()].map((entry) => entry.descriptor);
+}
+
+/** Distinct namespaces that have at least one registered descriptor. */
+export function listSettingNamespaces(): string[] {
+  return [...new Set(listSettingDescriptors().map((d) => d.namespace))];
+}
+
+/**
+ * Validate a candidate value against a registered descriptor's compiled schema.
+ * The single validation seam — #383 calls this on writes so the schema is the one
+ * source of truth. Returns `valid:false` with a reason when no descriptor exists.
+ */
+export function validateSettingValue(
+  namespace: string,
+  key: string,
+  value: unknown,
+): { valid: boolean; errors: string[] } {
+  ensureSeeded();
+  const entry = registry.get(descriptorId(namespace, key));
+  if (!entry) return { valid: false, errors: [`no descriptor registered for "${descriptorId(namespace, key)}"`] };
+  const valid = entry.validate(value) === true;
+  if (valid) return { valid: true, errors: [] };
+  const errors = (entry.validate.errors ?? []).map((e) => `${e.instancePath || "/"} ${e.message ?? "invalid"}`.trim());
+  return { valid: false, errors };
+}
+
+// ──────────────────────────────────────────────────────────────────────────
+// Built-in seeds — descriptors for today's `config`-table namespaces. Schemas
+// mirror the validators in src/config-store.ts; defaults mirror its *_DEFAULTS.
+// All current built-ins are `server-runtime` (config-table backed, runtime
+// mutable). Scope is left default (admin) here; #385 refines read/write tokens.
+// ──────────────────────────────────────────────────────────────────────────
+
+const STEWARD_SCHEMA: JSONSchema = {
+  type: "object",
+  additionalProperties: false,
+  required: ["enabled", "provider", "permissionMode", "keepaliveSeconds"],
+  properties: {
+    enabled: { type: "boolean" },
+    provider: { type: "string", enum: [...SPAWN_PROVIDERS] },
+    model: { type: "string", maxLength: 120 },
+    effort: { type: "string", enum: [...VALID_EFFORTS] },
+    permissionMode: { type: "string", enum: [...APPROVAL_MODES] },
+    keepaliveSeconds: { type: "integer", minimum: 0, maximum: 2_592_000 },
+  },
+};
+
+const INSIGHTS_SCHEMA: JSONSchema = {
+  type: "object",
+  additionalProperties: false,
+  required: ["enabled", "contextRatio", "introspection"],
+  properties: {
+    enabled: { type: "boolean" },
+    contextRatio: {
+      type: "object",
+      additionalProperties: false,
+      required: ["enabled"],
+      properties: { enabled: { type: "boolean" } },
+    },
+    introspection: {
+      type: "object",
+      additionalProperties: false,
+      required: ["enabled", "minTurns", "minContextRemaining"],
+      properties: {
+        enabled: { type: "boolean" },
+        minTurns: { type: "integer", minimum: 0, maximum: 1000 },
+        minContextRemaining: { type: "number", minimum: 0, maximum: 1 },
+      },
+    },
+  },
+};
+
+const CONTEXT_THRESHOLD_SCHEMA: JSONSchema = {
+  type: "object",
+  additionalProperties: false,
+  required: ["enabled", "advisoryUtilization", "hardBackstopUtilization", "bandSize"],
+  properties: {
+    enabled: { type: "boolean" },
+    advisoryUtilization: { type: "number", minimum: 0, maximum: 1 },
+    hardBackstopUtilization: { type: "number", minimum: 0, maximum: 1 },
+    bandSize: { type: "number", minimum: 0, maximum: 1 },
+  },
+};
+
+const NOTIFICATIONS_SCHEMA: JSONSchema = {
+  type: "object",
+  additionalProperties: false,
+  required: ["enabled", "branchLanded", "agentReady", "agentExited", "agentSpawnFailed", "contextThreshold"],
+  properties: {
+    enabled: { type: "boolean" },
+    branchLanded: { type: "boolean" },
+    agentReady: { type: "boolean" },
+    agentExited: { type: "boolean" },
+    agentSpawnFailed: { type: "boolean" },
+    contextThreshold: CONTEXT_THRESHOLD_SCHEMA,
+  },
+};
+
+const WORKSPACE_SCHEMA: JSONSchema = {
+  type: "object",
+  additionalProperties: false,
+  required: ["symlinkPaths"],
+  properties: {
+    symlinkPaths: {
+      type: "array",
+      maxItems: 100,
+      items: { type: "string", maxLength: 120 },
+    },
+  },
+};
+
+const LANDING_SCHEMA: JSONSchema = {
+  type: "object",
+  additionalProperties: false,
+  required: ["strategy"],
+  properties: {
+    strategy: { type: "string", enum: ["direct", "pr"] },
+  },
+};
+
+// Provider chat/reasoning capture toggles (source: runner/src/adapter.ts ProviderConfig).
+// NOTE (#383 coordination): provider config storage is being centralized in #383;
+// these are seeded instance-global under namespace "provider". Per-provider
+// (claude vs codex) host-addressing is #383's call — keep these minimal until then.
+const PROVIDER_CHAT_CAPTURE_SCHEMA: JSONSchema = {
+  type: "string",
+  enum: ["final", "full"],
+};
+
+const PROVIDER_REASONING_CAPTURE_SCHEMA: JSONSchema = {
+  type: "boolean",
+};
+
+export const PROVIDER_CONFIG_NAMESPACE = "provider-config";
+export const PROVIDER_CONFIG_SCHEMA: JSONSchema = {
+  type: "object",
+  additionalProperties: false,
+  required: [
+    "command",
+    "defaultArgs",
+    "env",
+    "pluginDirs",
+    "defaultCapabilities",
+    "defaultApprovalMode",
+    "defaultTags",
+    "chatCaptureMode",
+    "reasoningCapture",
+    "headless",
+  ],
+  properties: {
+    command: { type: "string", minLength: 1, maxLength: 500 },
+    defaultArgs: { type: "array", maxItems: 50, items: { type: "string", maxLength: 80 } },
+    env: { type: "object", additionalProperties: { type: "string" } },
+    pluginDirs: { type: "array", maxItems: 50, items: { type: "string", maxLength: 80 } },
+    defaultCapabilities: { type: "array", maxItems: 50, items: { type: "string", maxLength: 80 } },
+    defaultApprovalMode: { type: "string", maxLength: 80 },
+    defaultTags: { type: "array", maxItems: 50, items: { type: "string", maxLength: 80 } },
+    chatCaptureMode: { type: "string", enum: ["final", "full"] },
+    reasoningCapture: { type: "boolean" },
+    headless: {
+      type: "object",
+      additionalProperties: false,
+      required: ["tmuxPrefix", "shutdownTimeoutMs"],
+      properties: {
+        tmuxPrefix: { type: "string", minLength: 1, maxLength: 120 },
+        shutdownTimeoutMs: { type: "integer", minimum: 1 },
+      },
+    },
+  },
+};
+
+let seeded = false;
+
+/**
+ * Register the built-in descriptors. Idempotent: safe to call repeatedly (and is
+ * called lazily by the read accessors). #386 adds module-contributed descriptors
+ * on top via `registerSetting`.
+ */
+export function seedBuiltInSettings(): void {
+  if (seeded) return;
+  seeded = true;
+
+  registerSetting({
+    namespace: "steward",
+    key: "default",
+    schema: STEWARD_SCHEMA,
+    defaults: { enabled: false, provider: "claude", permissionMode: "open", keepaliveSeconds: 300 },
+    scope: { read: "settings:read:steward", write: "settings:write:steward" },
+    tier: "server-runtime",
+    display: { group: "Agents", label: "Steward", description: "Auto-provisioned steward that reconciles merges and commands.", order: 10 },
+  });
+
+  registerSetting({
+    namespace: "insights",
+    key: "default",
+    schema: INSIGHTS_SCHEMA,
+    defaults: {
+      enabled: true,
+      contextRatio: { enabled: true },
+      introspection: { enabled: true, minTurns: 4, minContextRemaining: 0.15 },
+    },
+    scope: { read: "settings:read:insights", write: "settings:write:insights" },
+    tier: "server-runtime",
+    display: { group: "Insights", label: "Insights", description: "Continuous self-improvement instrumentation toggles.", order: 20 },
+  });
+
+  registerSetting({
+    namespace: "notifications",
+    key: "default",
+    schema: NOTIFICATIONS_SCHEMA,
+    defaults: {
+      enabled: true,
+      branchLanded: true,
+      agentReady: true,
+      agentExited: true,
+      agentSpawnFailed: true,
+      contextThreshold: { enabled: true, advisoryUtilization: 0.7, hardBackstopUtilization: 0.9, bandSize: 0.1 },
+    },
+    scope: { read: "settings:read:notifications", write: "settings:write:notifications" },
+    tier: "server-runtime",
+    display: { group: "Notifications", label: "Lifecycle notifications", description: "Relay-driven lifecycle push notifications (#239).", order: 30 },
+  });
+
+  registerSetting({
+    namespace: "workspace",
+    key: "default",
+    schema: WORKSPACE_SCHEMA,
+    defaults: { symlinkPaths: ["AGENTS.md", ".claude-rig"] },
+    scope: { read: "settings:read:workspace", write: "settings:write:workspace" },
+    tier: "server-runtime",
+    display: { group: "Workspace", label: "Workspace provisioning", description: "Untracked paths symlinked into isolated worktrees.", order: 40 },
+  });
+
+  registerSetting({
+    namespace: "landing",
+    key: "default",
+    schema: LANDING_SCHEMA,
+    defaults: { strategy: "direct" },
+    scope: { read: "settings:read:landing", write: "settings:write:landing" },
+    tier: "server-runtime",
+    display: { group: "Workspace", label: "Landing strategy", description: "Default land strategy for workspace branches.", order: 41 },
+  });
+
+  registerSetting({
+    namespace: "provider",
+    key: "chatCaptureMode",
+    schema: PROVIDER_CHAT_CAPTURE_SCHEMA,
+    defaults: "full",
+    scope: { read: "settings:read:provider", write: "settings:write:provider" },
+    tier: "server-runtime",
+    display: { group: "Providers", label: "Chat capture mode", description: "How much provider output is captured into chat.", order: 50 },
+  });
+
+  registerSetting({
+    namespace: "provider",
+    key: "reasoningCapture",
+    schema: PROVIDER_REASONING_CAPTURE_SCHEMA,
+    defaults: true,
+    scope: { read: "settings:read:provider", write: "settings:write:provider" },
+    tier: "server-runtime",
+    display: { group: "Providers", label: "Reasoning capture", description: "Stream reasoning/tool steps into chat.", order: 51 },
+  });
+}
+
+export function registerProviderConfigSetting(input: {
+  host: string;
+  provider: string;
+  defaults: unknown;
+  display?: Partial<SettingDescriptor["display"]>;
+}): SettingDescriptor {
+  return registerSetting({
+    namespace: PROVIDER_CONFIG_NAMESPACE,
+    key: `${input.host}/${input.provider}`,
+    schema: PROVIDER_CONFIG_SCHEMA,
+    defaults: input.defaults,
+    scope: { read: "agent:read", write: SETTING_ADMIN_SCOPE },
+    tier: "server-runtime",
+    display: {
+      group: "Providers",
+      label: `${input.host} ${input.provider}`,
+      description: `Provider runtime configuration for ${input.provider} on ${input.host}.`,
+      order: 60,
+      ...input.display,
+    },
+  });
+}
+
+function ensureSeeded(): void {
+  if (!seeded) seedBuiltInSettings();
+}
+
+// Seed on import so any consumer of the registry sees the built-ins.
+seedBuiltInSettings();