agent-relay-server 0.60.1 → 0.61.0

package/src/recipe-validator.ts

@@ -1,6 +1,7 @@
 import type { MemoryType, Recipe, RecipeAgent, RecipeMemoryPolicy } from "./types";
 import { resolveProviderSelection, type ProviderEffort } from "agent-relay-sdk/provider-catalog";
 import { errMessage, isRecord } from "agent-relay-sdk";
+import { effectiveProviderCatalogList } from "./provider-catalog-store";
 
 class RecipeValidationError extends Error {}
 
@@ -50,7 +51,7 @@ function validateAgent(value: unknown): RecipeAgent {
   const model = optionalString(value.model, "agent.model");
   const effort = optionalEffort(value.effort, "agent.effort");
   try {
-    resolveProviderSelection({ provider, model, effort });
+    resolveProviderSelection({ provider, model, effort }, effectiveProviderCatalogList());
   } catch (error) {
     throw new RecipeValidationError(errMessage(error));
   }
@@ -103,8 +104,8 @@ function optionalString(value: unknown, field: string): string | undefined {
 
 function optionalEffort(value: unknown, field: string): ProviderEffort | undefined {
   if (value === undefined || value === null) return undefined;
-  if (value === "low" || value === "medium" || value === "high" || value === "xhigh" || value === "max") return value;
-  throw new RecipeValidationError(`${field} must be low, medium, high, xhigh, or max`);
+  if (typeof value !== "string") throw new RecipeValidationError(`${field} must be a string`);
+  return value.trim() as ProviderEffort || undefined;
 }
 
 function optionalBoolean(value: unknown, field: string): boolean | undefined {

package/src/routes/agents-spawn.ts

@@ -1,5 +1,5 @@
 // Auto-split from routes.ts (#299). Domain: agents-spawn.
-import { APPROVAL_MODES, SPAWN_PROVIDERS, VALID_EFFORTS, VALID_WORKSPACE_MODES, isRecord } from "agent-relay-sdk";
+import { APPROVAL_MODES, SPAWN_PROVIDERS, VALID_WORKSPACE_MODES, isRecord } from "agent-relay-sdk";
 import { McpAuthError, McpNotFoundError } from "../mcp-errors";
 import { VALID_AGENT_STATUSES, error, json, parseBody, type Handler } from "./_shared";
 import { ValidationError, listAgents } from "../db";
@@ -109,7 +109,7 @@ export const postAgentSpawn: Handler = async (req) => {
       orchestratorId: cleanString(parsed.body.orchestratorId, "orchestratorId", { max: 200 }),
       cwd: cleanString(parsed.body.cwd, "cwd", { max: 500 }),
       model: cleanString(parsed.body.model, "model", { max: 120 }),
-      effort: optionalEnum(parsed.body.effort, "effort", VALID_EFFORTS) as ProviderEffort | undefined,
+      effort: cleanString(parsed.body.effort, "effort", { max: 120 }) as ProviderEffort | undefined,
       approvalMode: optionalEnum(parsed.body.approvalMode, "approvalMode", APPROVAL_MODES) as SpawnApprovalMode | undefined,
       workspaceMode: optionalEnum(parsed.body.workspaceMode, "workspaceMode", VALID_WORKSPACE_MODES) as WorkspaceMode | undefined,
       label: cleanString(parsed.body.label, "label", { max: 120 }),

package/src/routes/index.ts

@@ -4,14 +4,14 @@ import { deleteAgentProfileRoute, getAgentProfileRoute, getAgentProfilesRoute, p
 import { deleteAgentTerminalSession, postAgentAction, postAgentPermissionDecision, postAgentPrompt, postAgentTerminalSession } from "./agent-sessions";
 import { deleteArtifactById, getArtifactById, getArtifactContent, getArtifacts, headArtifactContent, postArtifact } from "./artifacts";
 import { deleteAutomationById, getAutomationById, getAutomationRuns, getAutomations, patchAutomation, postAutomation, postAutomationRun } from "./automations";
-import { deleteCommandById, getProviderConfigRoute, getProviderConfigsRoute, getProvidersRoute, postProviderConfigTestRoute, putProviderConfigRoute } from "./provider-config";
+import { deleteCommandById, deleteProviderModelRoute, getProviderConfigRoute, getProviderConfigsRoute, getProvidersRoute, patchProviderModelRoute, postProviderConfigTestRoute, putProviderConfigRoute, putProviderModelRoute } from "./provider-config";
 import { deleteConfigKey, getConfigKey, getConfigKeyHistory, getConfigNamespace, putConfigKey } from "./config";
 import { deleteInboxDraftRoute, getChatHistoryImportsRoute, getInboxStateRoute, patchInboxThreadState, postChatHistoryImportRoute, putInboxDraft } from "./inbox";
 import { deleteMemoryRoute, getMemories, getMemoryBrokerInfo, getMemoryById, getMemoryStats, patchMemory, postMemory, postMemoryInject, postMemorySearch } from "./memory";
 import { deleteMessageById, getCursorRoute, getMessageById, getMessageDeliveryRoute, getMessageStatusRoute, getMessageThread, getMessages, getQueuedMessagesRoute, patchMessage, postClaimMessage, postMessage, postMessageDeliveryAction, postMessageDeliveryAttempt, postMessageReaction, postRenewMessageClaim, postSystemBroadcast } from "./messages";
 import { deleteOrchestratorById, getOrchestratorById, getOrchestrators, patchOrchestratorAgents, postOrchestrator, postOrchestratorAction, postOrchestratorHeartbeat } from "./orchestrator";
 import { deleteSpawnPolicyRoute, getSpawnPoliciesHealth, getSpawnPoliciesRoute, getSpawnPolicyHealth, getSpawnPolicyRoute, getSpawnPolicyStatus, postSpawnPolicyRestart, postSpawnPolicyStart, postSpawnPolicyStop, putSpawnPolicyRoute } from "./spawn-policy";
-import { deleteTokenProfileRoute, getTokenById, getTokenProfiles, getTokens, patchTokenProfile, postIntegrationRuntimeToken, postInteractiveRunnerRuntimeToken, postMcpRuntimeToken, postOrchestratorRunnerToken, postRuntimeTokenRenew, postToken, postTokenProfile, postTokenRevoke } from "./tokens";
+import { deleteTokenProfileRoute, getTokenById, getTokenMe, getTokenProfiles, getTokens, patchTokenProfile, postIntegrationRuntimeToken, postInteractiveRunnerRuntimeToken, postMcpRuntimeToken, postOrchestratorRunnerToken, postRuntimeTokenRenew, postToken, postTokenProfile, postTokenRevoke } from "./tokens";
 import { deleteWorkspaceById, getWorkspaceById, getWorkspaceDiagnostics, getWorkspaceDiff, getWorkspaceGitState, getWorkspaceMergePreview, getWorkspaceOrphans, getWorkspaceStewards, getWorkspaces, postWorkspaceAction, postWorkspaceCleanupStale, postWorkspaceOrphanReclaim } from "./workspaces";
 import { error, type Handler } from "./_shared";
 import { getActivityEvents, postActivityEvent } from "./activity";
@@ -30,6 +30,7 @@ import { getPlanByIdRoute, getPlansRoute } from "./plans";
 import { getBlackboardEntryRoute, getBlackboardRoute } from "./blackboard";
 import { getProjectEntriesRoute, getProjectEntryRoute, getProjectRoute, getProjectsRoute } from "./projects";
 import { getRecipeByName, getRecipeInstanceArtifacts, getRecipeInstanceById, getRecipeInstances, getRecipes, postRecipeInstanceArtifacts, postRecipeStart, postRecipeStop } from "./recipes";
+import { getSettingRoute, getSettingsNamespaceRoute, getSettingsRoute, putSettingRoute, putSettingsDefaultRoute } from "./settings";
 import { getStewardConfigRoute, getWorkspaceConfigRoute, putStewardConfigRoute, putWorkspaceConfigRoute } from "./steward";
 import { getTaskById, getTaskEvents, getTasks, patchTaskStatus, postClaimTask, postRenewTaskClaim } from "./tasks";
 import { getMyTeamRoute, getTeamOutcomesRoute, getTeamsRoute, postMyTeamDissolveRoute, putMyTeamBriefRoute } from "./teams";
@@ -168,6 +169,7 @@ const routes: Route[] = [
   route("GET", "/api/recipes/:name", getRecipeByName),
   route("GET", "/api/tokens", getTokens),
   route("POST", "/api/tokens", postToken),
+  route("GET", "/api/tokens/me", getTokenMe),
   route("POST", "/api/runtime-tokens/renew", postRuntimeTokenRenew),
   route("POST", "/api/runtime-tokens/interactive-runner", postInteractiveRunnerRuntimeToken),
   route("POST", "/api/runtime-tokens/mcp-client", postMcpRuntimeToken),
@@ -196,6 +198,11 @@ const routes: Route[] = [
   route("GET", "/api/insights/observations", getInsightsObservationsRoute),
   route("POST", "/api/insights/observations", postInsightsObservationRoute),
   route("POST", "/api/continuation-archives", postContinuationArchiveRoute),
+  route("GET", "/api/settings", getSettingsRoute),
+  route("GET", "/api/settings/:namespace", getSettingsNamespaceRoute),
+  route("GET", "/api/settings/:namespace/:key", getSettingRoute),
+  route("PUT", "/api/settings/:namespace", putSettingsDefaultRoute),
+  route("PUT", "/api/settings/:namespace/:key", putSettingRoute),
   route("GET", "/api/config/:namespace", getConfigNamespace),
   route("GET", "/api/config/:namespace/:key/history", getConfigKeyHistory),
   route("GET", "/api/config/:namespace/:key", getConfigKey),
@@ -213,6 +220,9 @@ const routes: Route[] = [
   route("GET", "/api/spawn-policy/:name/health", getSpawnPolicyHealth),
   route("GET", "/api/providers", getProvidersRoute),
   route("GET", "/api/providers/config", getProviderConfigsRoute),
+  route("PUT", "/api/providers/:provider/models/:alias", putProviderModelRoute),
+  route("PATCH", "/api/providers/:provider/models/:alias", patchProviderModelRoute),
+  route("DELETE", "/api/providers/:provider/models/:alias", deleteProviderModelRoute),
   route("GET", "/api/providers/:provider/config", getProviderConfigRoute),
   route("PUT", "/api/providers/:provider/config", putProviderConfigRoute),
   route("POST", "/api/providers/:provider/config/test", postProviderConfigTestRoute),

package/src/routes/insights.ts

@@ -3,11 +3,12 @@ import { ValidationError } from "../db";
 import { cleanString } from "../validation";
 import { emitConfigChanged } from "../sse";
 import { error, json, parseBody, type Handler } from "./_shared";
-import { getInsightsConfigEntry, setInsightsConfig } from "../config-store";
+import { getInsightsConfigEntry } from "../config-store";
 import { getObservationStats, listObservationProjects, listObservations, recordObservation } from "../insights-db";
+import { getRegisteredSettingEntry, setRegisteredSettingValue } from "./settings";
 import { isRecord } from "agent-relay-sdk";
 
-export const getInsightsConfigRoute: Handler = () => json(getInsightsConfigEntry());
+export const getInsightsConfigRoute: Handler = () => json(getRegisteredSettingEntry("insights", "default"));
 
 export const putInsightsConfigRoute: Handler = async (req) => {
   const parsed = await parseBody<unknown>(req);
@@ -17,7 +18,7 @@ export const putInsightsConfigRoute: Handler = async (req) => {
       ? parsed.body.value
       : parsed.body;
     const updatedBy = isRecord(parsed.body) ? cleanString(parsed.body.updatedBy, "updatedBy", { max: 200 }) : undefined;
-    const entry = setInsightsConfig(value, updatedBy);
+    const entry = setRegisteredSettingValue("insights", "default", value, updatedBy);
     emitConfigChanged(entry.namespace, entry.key, entry.version);
     return json(entry, entry.version === 1 ? 201 : 200);
   } catch (e) {

package/src/routes/provider-config.ts

@@ -2,14 +2,13 @@
 import { ValidationError, listOrchestrators } from "../db";
 import { applyCommandToRecipe } from "../recipe-runner";
 import { cleanString, cleanStringArray, optionalEnum } from "../validation";
-import { defaultProviderConfig, loadProviderConfig, providerConfigPublic, writeProviderConfig } from "../../runner/src/config";
 import { deleteCommand, getCommand } from "../commands-db";
-import { effectiveProviderCatalogList } from "../provider-catalog-store";
+import { effectiveProviderCatalogList, removeProviderModelOverride, setProviderModelDisabled, upsertProviderModelOverride } from "../provider-catalog-store";
 import { emitCommand, error, json, parseBody, type Handler } from "./_shared";
-import { isRecord } from "agent-relay-sdk";
-import { type ProviderConfig } from "../../runner/src/adapter";
-
-const VALID_PROVIDER_CONFIGS = ["claude", "codex"] as const;
+import { getProviderConfigEntry, listProviderConfigEntries, migrateLocalProviderConfigs, providerConfigPublic, setProviderConfig, VALID_PROVIDER_CONFIGS } from "../provider-config-store";
+import { emitConfigChanged } from "../sse";
+import { isRecord, type SpawnProvider } from "agent-relay-sdk";
+import type { ProviderModelCatalogEntry } from "agent-relay-sdk/provider-catalog";
 
 export const getProvidersRoute: Handler = () => {
   return json({
@@ -25,17 +24,72 @@ export const getProvidersRoute: Handler = () => {
   });
 };
 
-export const getProviderConfigsRoute: Handler = () => {
+export const getProviderConfigsRoute: Handler = (req) => {
+  const host = new URL(req.url).searchParams.get("host") ?? undefined;
+  migrateLocalProviderConfigs();
+  const entries = listProviderConfigEntries(host);
   return json(Object.fromEntries(VALID_PROVIDER_CONFIGS.map((provider) => {
-    const config = loadProviderConfig(provider);
-    return [provider, providerConfigPublic(config)];
+    return [provider, providerConfigPublic(entries[provider])];
   })));
 };
 
+export const putProviderModelRoute: Handler = async (req, params) => {
+  const provider = optionalEnum(params.provider, "provider", VALID_PROVIDER_CONFIGS) as SpawnProvider | undefined;
+  if (!provider) return error("provider required");
+  const alias = cleanString(params.alias, "alias", { required: true, max: 120 })!;
+  const parsed = await parseBody<unknown>(req);
+  if (!parsed.ok) return error(parsed.error, parsed.status);
+  try {
+    if (!isRecord(parsed.body)) return error("model body must be an object");
+    const entry = cleanProviderModelEntry(alias, parsed.body);
+    return json(upsertProviderModelOverride({
+      provider,
+      alias,
+      entry,
+      disabled: optionalBoolean(parsed.body.disabled, "disabled"),
+      updatedBy: cleanString(parsed.body.updatedBy, "updatedBy", { max: 120 }),
+    }));
+  } catch (e) {
+    if (e instanceof ValidationError) return error(e.message, 400);
+    throw e;
+  }
+};
+
+export const patchProviderModelRoute: Handler = async (req, params) => {
+  const provider = optionalEnum(params.provider, "provider", VALID_PROVIDER_CONFIGS) as SpawnProvider | undefined;
+  if (!provider) return error("provider required");
+  const alias = cleanString(params.alias, "alias", { required: true, max: 120 })!;
+  const parsed = await parseBody<unknown>(req);
+  if (!parsed.ok) return error(parsed.error, parsed.status);
+  try {
+    if (!isRecord(parsed.body)) return error("model patch body must be an object");
+    if (parsed.body.disabled === undefined) throw new ValidationError("disabled required");
+    return json(setProviderModelDisabled(provider, alias, optionalBoolean(parsed.body.disabled, "disabled") ?? false, cleanString(parsed.body.updatedBy, "updatedBy", { max: 120 })));
+  } catch (e) {
+    if (e instanceof ValidationError) return error(e.message, 400);
+    throw e;
+  }
+};
+
+export const deleteProviderModelRoute: Handler = (_req, params) => {
+  const provider = optionalEnum(params.provider, "provider", VALID_PROVIDER_CONFIGS) as SpawnProvider | undefined;
+  if (!provider) return error("provider required");
+  try {
+    const alias = cleanString(params.alias, "alias", { required: true, max: 120 })!;
+    return json(removeProviderModelOverride(provider, alias));
+  } catch (e) {
+    if (e instanceof ValidationError) return error(e.message, 400);
+    throw e;
+  }
+};
+
 export const getProviderConfigRoute: Handler = (_req, params) => {
   const provider = optionalEnum(params.provider, "provider", VALID_PROVIDER_CONFIGS);
   if (!provider) return error("provider required");
-  return json(providerConfigPublic(loadProviderConfig(provider)));
+  const host = new URL(_req.url).searchParams.get("host") ?? undefined;
+  const includeSecrets = new URL(_req.url).searchParams.get("includeSecrets") === "1";
+  migrateLocalProviderConfigs();
+  return json(providerConfigPublic(getProviderConfigEntry(provider, host), { maskEnv: !includeSecrets }));
 };
 
 export const putProviderConfigRoute: Handler = async (req, params) => {
@@ -45,23 +99,11 @@ export const putProviderConfigRoute: Handler = async (req, params) => {
   if (!parsed.ok) return error(parsed.error, parsed.status);
   try {
     if (!isRecord(parsed.body)) return error("provider config body must be an object");
-    const defaults = defaultProviderConfig(provider);
-    const headless = isRecord(parsed.body.headless) ? parsed.body.headless : {};
-    const config: ProviderConfig = {
-      command: cleanString(parsed.body.command, "command", { required: true, max: 500 })!,
-      defaultArgs: cleanStringArray(parsed.body.defaultArgs, "defaultArgs", { itemMax: 80, maxItems: 50 }) ?? defaults.defaultArgs,
-      env: cleanEnvRecord(parsed.body.env),
-      pluginDirs: cleanStringArray(parsed.body.pluginDirs, "pluginDirs", { itemMax: 80, maxItems: 50 }) ?? defaults.pluginDirs,
-      defaultCapabilities: cleanStringArray(parsed.body.defaultCapabilities, "defaultCapabilities", { itemMax: 80, maxItems: 50 }) ?? defaults.defaultCapabilities,
-      defaultApprovalMode: cleanString(parsed.body.defaultApprovalMode, "defaultApprovalMode", { max: 80 }) ?? defaults.defaultApprovalMode,
-      defaultTags: cleanStringArray(parsed.body.defaultTags, "defaultTags", { itemMax: 80, maxItems: 50 }) ?? defaults.defaultTags,
-      chatCaptureMode: (optionalEnum(parsed.body.chatCaptureMode, "chatCaptureMode", ["final", "full"]) ?? defaults.chatCaptureMode) as "final" | "full",
-      headless: {
-        tmuxPrefix: cleanString(headless.tmuxPrefix, "headless.tmuxPrefix", { max: 120 }) ?? defaults.headless.tmuxPrefix,
-        shutdownTimeoutMs: cleanPositiveInt(headless.shutdownTimeoutMs, "headless.shutdownTimeoutMs") ?? defaults.headless.shutdownTimeoutMs,
-      },
-    };
-    return json(providerConfigPublic(writeProviderConfig(provider, config)));
+    const host = new URL(req.url).searchParams.get("host") ?? undefined;
+    const updatedBy = cleanString(parsed.body.updatedBy, "updatedBy", { max: 200 });
+    const entry = setProviderConfig(provider, parsed.body, { host, updatedBy });
+    emitConfigChanged(entry.namespace, entry.key, entry.version);
+    return json(providerConfigPublic(entry), entry.version === 1 ? 201 : 200);
   } catch (e) {
     if (e instanceof ValidationError) return error(e.message, 400);
     throw e;
@@ -71,7 +113,8 @@ export const putProviderConfigRoute: Handler = async (req, params) => {
 export const postProviderConfigTestRoute: Handler = async (_req, params) => {
   const provider = optionalEnum(params.provider, "provider", VALID_PROVIDER_CONFIGS);
   if (!provider) return error("provider required");
-  const config = loadProviderConfig(provider);
+  const host = new URL(_req.url).searchParams.get("host") ?? undefined;
+  const config = getProviderConfigEntry(provider, host).value;
   const proc = Bun.spawn(["bash", "-lc", `command -v "$1"`, "bash", config.command], {
     stdout: "pipe",
     stderr: "pipe",
@@ -82,22 +125,27 @@ export const postProviderConfigTestRoute: Handler = async (_req, params) => {
     new Response(proc.stderr).text(),
   ]);
   return json({ ok: exitCode === 0, command: config.command, path: stdout.trim(), error: stderr.trim() }, exitCode === 0 ? 200 : 422);
-};
+}
 
-function cleanEnvRecord(value: unknown): Record<string, string> {
-  if (value === undefined) return {};
-  if (!isRecord(value)) throw new ValidationError("env must be an object");
-  const env: Record<string, string> = {};
-  for (const [key, item] of Object.entries(value)) {
-    if (typeof item !== "string") throw new ValidationError(`env.${key} must be a string`);
-    env[key] = item;
-  }
-  return env;
+function cleanProviderModelEntry(alias: string, body: Record<string, unknown>): ProviderModelCatalogEntry {
+  const source = isRecord(body.entry) ? body.entry : body;
+  const efforts = cleanStringArray(source.efforts, "efforts", { itemMax: 120, maxItems: 50 }) ?? [];
+  const defaultEffort = cleanString(source.defaultEffort, "defaultEffort", { max: 120 });
+  if (defaultEffort && !efforts.includes(defaultEffort)) throw new ValidationError("defaultEffort must be included in efforts");
+  return {
+    alias,
+    label: cleanString(source.label, "label", { required: true, max: 120 })!,
+    providerModel: cleanString(source.providerModel, "providerModel", { required: true, max: 160 })!,
+    efforts,
+    ...(defaultEffort ? { defaultEffort } : {}),
+    ...(isRecord(source.limits) ? { limits: source.limits as ProviderModelCatalogEntry["limits"] } : {}),
+    ...(isRecord(source.capabilities) ? { capabilities: source.capabilities as unknown as ProviderModelCatalogEntry["capabilities"] } : {}),
+  };
 }
 
-function cleanPositiveInt(value: unknown, field: string): number | undefined {
-  if (value === undefined) return undefined;
-  if (typeof value !== "number" || !Number.isSafeInteger(value) || value <= 0) throw new ValidationError(`${field} must be a positive integer`);
+function optionalBoolean(value: unknown, field: string): boolean | undefined {
+  if (value === undefined || value === null) return undefined;
+  if (typeof value !== "boolean") throw new ValidationError(`${field} must be a boolean`);
   return value;
 }
 

package/src/routes/settings.ts

@@ -0,0 +1,127 @@
+// Auto-split from routes.ts (#299). Domain: schema-driven settings.
+import { ValidationError } from "../db";
+import { getConfig, setConfig } from "../config-store";
+import { ensureProviderConfigDescriptors, migrateLocalProviderConfigs } from "../provider-config-store";
+import { getSettingDescriptor, listSettingDescriptors, validateSettingValue, PROVIDER_CONFIG_NAMESPACE } from "../settings/registry";
+import { isRequestAuthorizedFor } from "../security";
+import { cleanString } from "../validation";
+import { emitConfigChanged } from "../sse";
+import { error, json, normalizeConfigPathParam, parseBody, type Handler } from "./_shared";
+import { isRecord, type ConfigEntry, type SettingDescriptor, type SettingEntry } from "agent-relay-sdk";
+
+type SettingEnvelope = SettingEntry;
+
+export const getSettingsRoute: Handler = (req) => {
+  migrateLocalProviderConfigs();
+  ensureProviderConfigDescriptors();
+  return json({ settings: listVisibleSettings(req) });
+};
+
+export const getSettingsNamespaceRoute: Handler = (req, params) => {
+  const namespace = normalizeConfigPathParam(params.namespace, "namespace");
+  migrateLocalProviderConfigs();
+  ensureProviderConfigDescriptors();
+  return json({ settings: listVisibleSettings(req).filter((setting) => setting.namespace === namespace) });
+};
+
+export const getSettingRoute: Handler = (req, params) => {
+  const namespace = normalizeConfigPathParam(params.namespace, "namespace");
+  const key = normalizeConfigPathParam(params.key, "key");
+  migrateLocalProviderConfigs();
+  ensureProviderConfigDescriptors(namespace === PROVIDER_CONFIG_NAMESPACE ? [key] : []);
+  const descriptor = getSettingDescriptor(namespace, key);
+  if (!descriptor) return error("setting not found", 404);
+  const readable = canAccessSetting(req, descriptor.scope.read);
+  if (!readable) return error("forbidden", 403);
+  return json(settingEnvelope(req, descriptor));
+};
+
+export const putSettingsDefaultRoute: Handler = (req, params) => putSetting(req, params.namespace, "default");
+export const putSettingRoute: Handler = (req, params) => putSetting(req, params.namespace, params.key);
+
+export function getRegisteredSettingEntry(namespace: string, key: string): ConfigEntry | null {
+  ensureProviderConfigDescriptors(namespace === PROVIDER_CONFIG_NAMESPACE ? [key] : []);
+  const descriptor = getSettingDescriptor(namespace, key);
+  return descriptor ? currentSettingEntry(descriptor) : null;
+}
+
+export function setRegisteredSettingValue(namespace: string, key: string, value: unknown, updatedBy?: string): ConfigEntry {
+  ensureProviderConfigDescriptors(namespace === PROVIDER_CONFIG_NAMESPACE ? [key] : []);
+  const descriptor = getSettingDescriptor(namespace, key);
+  if (!descriptor) throw new ValidationError("setting not found");
+  const merged = mergeSettingDefaults(descriptor.defaults, value);
+  const validation = validateSettingValue(namespace, key, merged);
+  if (!validation.valid) throw new ValidationError(validation.errors.join("; "));
+  return setConfig(namespace, key, merged, updatedBy);
+}
+
+async function putSetting(req: Request, namespaceRaw: string | undefined, keyRaw: string | undefined): Promise<Response> {
+  const namespace = normalizeConfigPathParam(namespaceRaw, "namespace");
+  const key = normalizeConfigPathParam(keyRaw, "key");
+  const parsed = await parseBody<unknown>(req);
+  if (!parsed.ok) return error(parsed.error, parsed.status);
+  if (!isRecord(parsed.body)) return error("JSON object body required", 400);
+  if (!Object.prototype.hasOwnProperty.call(parsed.body, "value")) return error("value required", 400);
+
+  try {
+    migrateLocalProviderConfigs();
+    ensureProviderConfigDescriptors(namespace === PROVIDER_CONFIG_NAMESPACE ? [key] : []);
+    const descriptor = getSettingDescriptor(namespace, key);
+    if (!descriptor) return error("setting not found", 404);
+    if (descriptor.tier !== "server-runtime") return error("setting is read-only", 403);
+    if (!canAccessSetting(req, descriptor.scope.write)) return error("forbidden", 403);
+    const updatedBy = cleanString(parsed.body.updatedBy, "updatedBy", { max: 200 });
+    const validation = validateSettingValue(namespace, key, parsed.body.value);
+    if (!validation.valid) return json({ error: "invalid setting value", details: validation.errors }, 400);
+    const entry = setConfig(namespace, key, parsed.body.value, updatedBy);
+    emitConfigChanged(entry.namespace, entry.key, entry.version);
+    return json(settingEnvelope(req, descriptor, entry), entry.version === 1 ? 201 : 200);
+  } catch (e) {
+    if (e instanceof ValidationError) return error(e.message, 400);
+    throw e;
+  }
+}
+
+function listVisibleSettings(req: Request): SettingEnvelope[] {
+  return listSettingDescriptors()
+    .map((descriptor) => settingEnvelope(req, descriptor))
+    .filter((setting) => setting.readable);
+}
+
+function settingEnvelope(req: Request, descriptor: SettingDescriptor, entry = currentSettingEntry(descriptor)): SettingEnvelope {
+  return {
+    ...descriptor,
+    value: entry.value,
+    version: entry.version,
+    updatedAt: entry.updatedAt,
+    updatedBy: entry.updatedBy,
+    readable: canAccessSetting(req, descriptor.scope.read),
+    writable: descriptor.tier === "server-runtime" && canAccessSetting(req, descriptor.scope.write),
+  };
+}
+
+function currentSettingEntry(descriptor: SettingDescriptor): ConfigEntry {
+  const entry = getConfig(descriptor.namespace, descriptor.key);
+  if (entry) return entry;
+  return {
+    namespace: descriptor.namespace,
+    key: descriptor.key,
+    value: descriptor.defaults,
+    version: 0,
+    updatedAt: "default",
+    updatedBy: "system",
+  };
+}
+
+function canAccessSetting(req: Request, scope: string): boolean {
+  return isRequestAuthorizedFor(req, { scope });
+}
+
+function mergeSettingDefaults(defaults: unknown, value: unknown): unknown {
+  if (!isRecord(defaults) || !isRecord(value)) return value;
+  const merged: Record<string, unknown> = { ...defaults };
+  for (const [key, item] of Object.entries(value)) {
+    merged[key] = mergeSettingDefaults(defaults[key], item);
+  }
+  return merged;
+}

package/src/routes/steward.ts

@@ -3,10 +3,10 @@ import { ValidationError } from "../db";
 import { cleanString } from "../validation";
 import { emitConfigChanged } from "../sse";
 import { error, json, parseBody, type Handler } from "./_shared";
-import { getStewardConfigEntry, getWorkspaceConfigEntry, setStewardConfig, setWorkspaceConfig } from "../config-store";
+import { getRegisteredSettingEntry, setRegisteredSettingValue } from "./settings";
 import { isRecord } from "agent-relay-sdk";
 
-export const getStewardConfigRoute: Handler = () => json(getStewardConfigEntry());
+export const getStewardConfigRoute: Handler = () => json(getRegisteredSettingEntry("steward", "default"));
 
 export const putStewardConfigRoute: Handler = async (req) => {
   const parsed = await parseBody<unknown>(req);
@@ -16,7 +16,7 @@ export const putStewardConfigRoute: Handler = async (req) => {
       ? parsed.body.value
       : parsed.body;
     const updatedBy = isRecord(parsed.body) ? cleanString(parsed.body.updatedBy, "updatedBy", { max: 200 }) : undefined;
-    const entry = setStewardConfig(value, updatedBy);
+    const entry = setRegisteredSettingValue("steward", "default", value, updatedBy);
     emitConfigChanged(entry.namespace, entry.key, entry.version);
     return json(entry, entry.version === 1 ? 201 : 200);
   } catch (e) {
@@ -25,7 +25,7 @@ export const putStewardConfigRoute: Handler = async (req) => {
   }
 };
 
-export const getWorkspaceConfigRoute: Handler = () => json(getWorkspaceConfigEntry());
+export const getWorkspaceConfigRoute: Handler = () => json(getRegisteredSettingEntry("workspace", "default"));
 
 export const putWorkspaceConfigRoute: Handler = async (req) => {
   const parsed = await parseBody<unknown>(req);
@@ -35,7 +35,7 @@ export const putWorkspaceConfigRoute: Handler = async (req) => {
       ? parsed.body.value
       : parsed.body;
     const updatedBy = isRecord(parsed.body) ? cleanString(parsed.body.updatedBy, "updatedBy", { max: 200 }) : undefined;
-    const entry = setWorkspaceConfig(value, updatedBy);
+    const entry = setRegisteredSettingValue("workspace", "default", value, updatedBy);
     emitConfigChanged(entry.namespace, entry.key, entry.version);
     return json(entry, entry.version === 1 ? 201 : 200);
   } catch (e) {

package/src/routes/tokens.ts

@@ -4,12 +4,43 @@ import { ValidationError, getOrchestrator, upsertIntegrationRegistry } from "../
 import { auditEvent, authAuditMetadata, authorizeRoute, error, isRootCredentialRequest, json, parseBody, type Handler } from "./_shared";
 import { cleanString, cleanStringArray, cleanTokenConstraints, optionalEnum } from "../validation";
 import { createToken, deleteTokenProfile, getToken, getTokenProfile, listTokenProfiles, listTokens, renewToken, revokeToken, updateTokenProfile, upsertTokenProfile } from "../token-db";
-import { getComponentAuth } from "../security";
+import { getComponentAuth, getIntegrationAuth, isAuthorized } from "../security";
 import { issueIntegrationRuntimeToken, issueInteractiveRunnerRuntimeToken, issueMcpRuntimeToken, reissueRunnerRuntimeToken } from "../runtime-tokens";
 import { type SpawnProvider } from "../types";
 
 export const getTokens: Handler = () => json(listTokens());
 
+export const getTokenMe: Handler = (req) => {
+  const component = getComponentAuth(req);
+  if (component) {
+    return json({
+      actor: component.sub,
+      kind: "component",
+      role: component.role,
+      scopes: component.scope,
+      constraints: component.constraints,
+      jti: component.jti,
+      exp: component.exp,
+    });
+  }
+
+  const integration = getIntegrationAuth(req);
+  if (integration) {
+    return json({
+      actor: integration.name,
+      kind: "integration",
+      scopes: integration.scopes,
+      targets: integration.targets,
+      channels: integration.channels,
+    });
+  }
+
+  if (isAuthorized(req)) {
+    return json({ actor: "server", kind: "server", scopes: ["*"] });
+  }
+  return error("unauthorized", 401);
+};
+
 function cleanTtlSeconds(value: unknown): number | undefined {
   if (value === undefined || value === null || value === "") return undefined;
   if (typeof value !== "number" || !Number.isSafeInteger(value) || value <= 0) {

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