agent-relay-server 0.60.1 → 0.61.1

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/orchestrator.ts

@@ -1,6 +1,7 @@
 // Auto-split from routes.ts (#299). Domain: orchestrator.
 import { APPROVAL_MODES, SPAWN_PROVIDERS, VALID_WORKSPACE_MODES, isRecord } from "agent-relay-sdk";
 import { CONTRACT_VERSIONS, parseRuntimeCapabilities, parseRuntimeContracts, parseRuntimePackage, type RuntimeCapabilities, type RuntimeContracts, type RuntimePackageMetadata } from "../contracts";
+import { notifyAgentOffline } from "../agent-lifecycle-events";
 import { VERSION } from "../config";
 import { ValidationError, deleteOrchestrator, getOrchestrator, listOrchestrators, orchestratorHeartbeat, recordAgentExitDiagnostics, setOrchestratorUpgradeState, updateManagedAgents, upsertOrchestrator } from "../db";
 import { auditEvent, authAuditMetadata, authorizeRoute, cleanJsonArray, cleanSafeNumber, dashboardAttribution, emitCommand, error, isRootCredentialRequest, json, parseBody, spawnRequestId, type Handler } from "./_shared";
@@ -201,7 +202,15 @@ export const patchOrchestratorAgents: Handler = async (req, params) => {
     const updated = updateManagedAgents(params.id!, cleaned);
     for (const exited of exitedAgents) {
       const agent = recordAgentExitDiagnostics(exited.agentId, exited);
-      if (agent) emitAgentStatus(agent.id);
+      if (agent) {
+        emitAgentStatus(agent.id);
+        // #466 — fast exit path must wake the spawn-parent. recordAgentExitDiagnostics already
+        // flipped the agent offline (above), so the stale-agent-reaper will structurally skip it
+        // (its WHERE excludes status='offline'), guaranteeing a single notifyAgentOffline emission.
+        // notifyAgentOffline no-ops for non-spawned agents. Only fire when we actually recorded the
+        // exit (agent !== null) so an already-offline row can't double-notify.
+        notifyAgentOffline(exited.agentId, exitReason(exited));
+      }
       auditEvent({
         clientId: [
           "managed-session-exit",
@@ -248,6 +257,17 @@ export const patchOrchestratorAgents: Handler = async (req, params) => {
   }
 };
 
+// #466 — derive a human-meaningful offline cause for the spawn-parent notification from the exit
+// diagnostics, in preference to the reaper's generic "heartbeat lost". Prefer the captured
+// lastError, then the systemd result (e.g. "success", "signal"), else a plain fallback.
+function exitReason(exited: ManagedSessionExitDiagnostics): string {
+  const lastError = exited.lastError?.trim();
+  if (lastError) return lastError;
+  const result = exited.systemd?.result?.trim();
+  if (result) return `exited (${result})`;
+  return "exited";
+}
+
 function cleanManagedSessionExitDiagnostics(value: unknown, index: number): ManagedSessionExitDiagnostics {
   if (!isRecord(value)) throw new ValidationError(`exitedAgents[${index}] must be an object`);
   const provider = optionalEnum(value.provider, `exitedAgents[${index}].provider`, SPAWN_PROVIDERS);

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