agent-relay-server 0.60.0 → 0.61.0

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,11 +30,13 @@ 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";
 import { postTeamDissolveByIdRoute } from "./teams";
 import { deleteTeamTemplateRoute, getTeamTemplateRoute, getTeamTemplatesRoute, postTeamTemplateRoute, putTeamTemplateRoute } from "./team-templates";
+import { getMergePauseById, getMergePauses, postMergePause, postMergePauseRenew, postMergePauseResume } from "./merges";
 import { postMcp } from "../mcp";
 import { postOrchestratorBootstrap, postOrchestratorBootstrapExchange } from "./orchestrator-bootstrap";
 
@@ -139,6 +141,12 @@ const routes: Route[] = [
   route("POST", "/api/workspaces/:id/actions", postWorkspaceAction),
   route("DELETE", "/api/workspaces/:id", deleteWorkspaceById),
 
+  route("GET", "/api/merges/pauses", getMergePauses),
+  route("POST", "/api/merges/pause", postMergePause),
+  route("POST", "/api/merges/resume", postMergePauseResume),
+  route("POST", "/api/merges/renew", postMergePauseRenew),
+  route("GET", "/api/merges/pauses/:id", getMergePauseById),
+
   route("POST", "/api/system/broadcast", postSystemBroadcast),
   route("GET", "/api/teams", getTeamsRoute),
   route("GET", "/api/teams/outcomes", getTeamOutcomesRoute),
@@ -161,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),
@@ -189,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),
@@ -206,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/merges.ts

@@ -0,0 +1,95 @@
+// Auto-merge coordination routes. Generic pause/resume primitive for callers
+// that need Relay's auto-merge sweep to defer a target briefly (#448).
+import { isRecord } from "agent-relay-sdk";
+import { ValidationError } from "../db";
+import { getAutoMergePause, listAutoMergePauses, pauseAutoMerge, renewAutoMergePause, resumeAutoMerge } from "../services/merge-pause";
+import { cleanString } from "../validation";
+import { authAuditMetadata, authorizeRoute, error, json, parseBody, type Handler } from "./_shared";
+
+function cleanTtlMs(value: unknown): number | undefined {
+  if (value === undefined || value === null || value === "") return undefined;
+  if (typeof value !== "number" || !Number.isSafeInteger(value) || value <= 0) {
+    throw new ValidationError("ttlMs must be a positive integer");
+  }
+  return value;
+}
+
+function actorFromRequest(req: Request): string {
+  const audit = authAuditMetadata(req);
+  const auth = isRecord(audit.auth) ? audit.auth : undefined;
+  return typeof auth?.sub === "string" ? auth.sub
+    : typeof auth?.name === "string" ? auth.name
+    : "root";
+}
+
+export const getMergePauses: Handler = (req) => {
+  const denied = authorizeRoute(req, { scope: "command:read" });
+  if (denied) return denied;
+  return json({ pauses: listAutoMergePauses() });
+};
+
+export const postMergePause: Handler = async (req) => {
+  const denied = authorizeRoute(req, { scope: "command:write" });
+  if (denied) return denied;
+  const parsed = await parseBody<unknown>(req);
+  if (!parsed.ok) return error(parsed.error, parsed.status);
+  try {
+    if (!isRecord(parsed.body)) return error("body required");
+    const repoRoot = cleanString(parsed.body.repoRoot, "repoRoot", { required: true, max: 1000 })!;
+    const baseRef = cleanString(parsed.body.baseRef, "baseRef", { max: 240 }) ?? "main";
+    const holder = cleanString(parsed.body.holder, "holder", { max: 240 }) ?? actorFromRequest(req);
+    const reason = cleanString(parsed.body.reason, "reason", { max: 500 });
+    const ttlMs = cleanTtlMs(parsed.body.ttlMs);
+    const result = pauseAutoMerge({ repoRoot, baseRef, holder, reason, ttlMs });
+    if (!result.ok) {
+      return json({ error: "merge target already paused", pause: result.pause }, 409);
+    }
+    return json({ pause: result.pause }, 201);
+  } catch (e) {
+    if (e instanceof ValidationError) return error(e.message, 400);
+    throw e;
+  }
+};
+
+export const postMergePauseRenew: Handler = async (req) => {
+  const denied = authorizeRoute(req, { scope: "command:write" });
+  if (denied) return denied;
+  const parsed = await parseBody<unknown>(req);
+  if (!parsed.ok) return error(parsed.error, parsed.status);
+  try {
+    if (!isRecord(parsed.body)) return error("body required");
+    const id = cleanString(parsed.body.id, "id", { required: true, max: 120 })!;
+    const ttlMs = cleanTtlMs(parsed.body.ttlMs);
+    const pause = renewAutoMergePause(id, ttlMs);
+    return pause ? json({ pause }) : error("merge pause not found or expired", 404);
+  } catch (e) {
+    if (e instanceof ValidationError) return error(e.message, 400);
+    throw e;
+  }
+};
+
+export const postMergePauseResume: Handler = async (req) => {
+  const denied = authorizeRoute(req, { scope: "command:write" });
+  if (denied) return denied;
+  const parsed = await parseBody<unknown>(req);
+  if (!parsed.ok) return error(parsed.error, parsed.status);
+  try {
+    if (!isRecord(parsed.body)) return error("body required");
+    const id = cleanString(parsed.body.id, "id", { max: 120 });
+    const repoRoot = cleanString(parsed.body.repoRoot, "repoRoot", { max: 1000 });
+    const baseRef = cleanString(parsed.body.baseRef, "baseRef", { max: 240 });
+    if (!id && !repoRoot) return error("id or repoRoot required", 400);
+    const released = resumeAutoMerge(id ? { id } : { repoRoot: repoRoot!, baseRef: baseRef ?? "main" });
+    return json({ released });
+  } catch (e) {
+    if (e instanceof ValidationError) return error(e.message, 400);
+    throw e;
+  }
+};
+
+export const getMergePauseById: Handler = (req, params) => {
+  const denied = authorizeRoute(req, { scope: "command:read" });
+  if (denied) return denied;
+  const pause = getAutoMergePause(params.id!);
+  return pause ? json(pause) : error("merge pause not found", 404);
+};

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) {