agent-relay-server 0.60.0 → 0.61.0

package/src/mcp-merge-tools.ts

@@ -0,0 +1,66 @@
+import { ValidationError } from "./db";
+import { McpNotFoundError } from "./mcp-errors";
+import { authContextFromMcp } from "./services/auth-context";
+import { listAutoMergePauses, pauseAutoMerge, renewAutoMergePause, resumeAutoMerge } from "./services/merge-pause";
+import { cleanString } from "./validation";
+
+export const MERGE_TOOLS = [
+  { name: "relay_merge_pauses", description: "List active auto-merge pauses. These are repo/base-level holds that make the workspace auto-merge job yield during release or build critical sections.", requiredScopes: ["command:read"], inputSchema: { type: "object", properties: {}, additionalProperties: false } },
+  {
+    name: "relay_merge_pause",
+    description: "Pause workspace auto-merge for one repo/base pair with a TTL. Existing active pause for the same target is returned as a conflict instead of replacing its holder.",
+    requiredScopes: ["command:write"],
+    inputSchema: {
+      type: "object",
+      properties: {
+        repoRoot: { type: "string", description: "Repository root whose auto-merge should pause." },
+        baseRef: { type: "string", description: "Base branch/ref to pause (default main)." },
+        ttlMs: { type: "integer", minimum: 1, description: "Pause TTL in milliseconds. Defaults to the server's merge-pause TTL." },
+        reason: { type: "string" },
+        holder: { type: "string", description: "Optional human-readable holder. Defaults to the authenticated caller." },
+      },
+      required: ["repoRoot"],
+      additionalProperties: false,
+    },
+  },
+  { name: "relay_merge_renew", description: "Renew an active auto-merge pause by id, extending its TTL from now.", requiredScopes: ["command:write"], inputSchema: { type: "object", properties: { id: { type: "string" }, ttlMs: { type: "integer", minimum: 1 } }, required: ["id"], additionalProperties: false } },
+  { name: "relay_merge_resume", description: "Release an auto-merge pause by id, or by repoRoot/baseRef.", requiredScopes: ["command:write"], inputSchema: { type: "object", properties: { id: { type: "string" }, repoRoot: { type: "string" }, baseRef: { type: "string", description: "Base branch/ref (default main when repoRoot is used)." } }, additionalProperties: false } },
+] satisfies Array<{ name: string; description: string; requiredScopes: string[]; inputSchema: Record<string, unknown> }>;
+
+type McpAuthLike = Parameters<typeof authContextFromMcp>[0];
+
+export function relayMergeTool(auth: McpAuthLike, name: string, args: Record<string, unknown>): Record<string, unknown> {
+  const ctx = authContextFromMcp(auth);
+  if (name === "relay_merge_pauses") {
+    const pauses = listAutoMergePauses();
+    return { pauses, count: pauses.length };
+  }
+  if (name === "relay_merge_pause") {
+    const result = pauseAutoMerge({
+      repoRoot: cleanString(args.repoRoot, "repoRoot", { required: true, max: 1024 })!,
+      baseRef: cleanString(args.baseRef, "baseRef", { max: 240 }),
+      holder: cleanString(args.holder, "holder", { max: 240 }) ?? ctx.callerAgentId ?? ctx.actor.id,
+      reason: cleanString(args.reason, "reason", { max: 1000 }),
+      ttlMs: optionalPositiveInt(args.ttlMs, "ttlMs"),
+    });
+    return result.ok ? { ok: true, pause: result.pause } : { ok: false, error: "merge target already paused", pause: result.pause };
+  }
+  if (name === "relay_merge_renew") {
+    const pause = renewAutoMergePause(cleanString(args.id, "id", { required: true, max: 120 })!, optionalPositiveInt(args.ttlMs, "ttlMs"));
+    if (!pause) throw new McpNotFoundError("merge pause not found or expired");
+    return { pause };
+  }
+  if (name === "relay_merge_resume") {
+    const id = cleanString(args.id, "id", { max: 120 });
+    const repoRoot = cleanString(args.repoRoot, "repoRoot", { max: 1024 });
+    if (!id && !repoRoot) throw new ValidationError("id or repoRoot required");
+    return { released: resumeAutoMerge({ id, repoRoot, baseRef: cleanString(args.baseRef, "baseRef", { max: 240 }) }) };
+  }
+  throw new ValidationError(`unknown tool: ${name}`);
+}
+
+function optionalPositiveInt(value: unknown, field: string): number | undefined {
+  if (value === undefined || value === null) return undefined;
+  if (typeof value !== "number" || !Number.isSafeInteger(value) || value <= 0) throw new ValidationError(`${field} must be a positive integer`);
+  return value;
+}

package/src/mcp-provider-catalog.ts

@@ -0,0 +1,9 @@
+import { VALID_EFFORTS, isRecord } from "agent-relay-sdk";
+import { effectiveProviderEffortLevels } from "./provider-catalog-store";
+
+export function providerCatalogToolInputSchema(name: string, inputSchema: Record<string, unknown>): Record<string, unknown> {
+  if (name !== "relay_spawn_agent") return inputSchema;
+  const efforts = effectiveProviderEffortLevels();
+  const properties = isRecord(inputSchema.properties) ? inputSchema.properties : {};
+  return { ...inputSchema, properties: { ...properties, effort: { type: "string", enum: efforts.length ? efforts : VALID_EFFORTS } } };
+}

package/src/mcp.ts

@@ -50,9 +50,9 @@ import { PLAN_TOOLS, relayPlanTool } from "./mcp-plan-tools";
 import { TEAM_TOOLS, relayTeamTool } from "./mcp-team-tools";
 import { BLACKBOARD_TOOLS, relayBlackboardTool } from "./mcp-blackboard-tools";
 import { PROJECT_TOOLS, relayProjectTool } from "./mcp-project-tools";
-import { NOTIFICATION_SUBSCRIPTION_TOOLS, relayNotificationSubscriptionTool } from "./mcp-notification-subscription-tools";
+import { NOTIFICATION_SUBSCRIPTION_TOOLS, relayNotificationSubscriptionTool } from "./mcp-notification-subscription-tools"; import { MERGE_TOOLS, relayMergeTool } from "./mcp-merge-tools";
 import { PROJECT_INSTRUCTION_POLICY_NAMES, parseProjectInstructions } from "./project-instructions";
-import { AGENT_ACTION_TOOL, relayAgentAction } from "./mcp-agent-action";
+import { AGENT_ACTION_TOOL, relayAgentAction } from "./mcp-agent-action"; import { providerCatalogToolInputSchema } from "./mcp-provider-catalog";
 import type { ActivityKind, AgentLifecycle, ArtifactKind, ArtifactSensitivity, AttachmentRef, Command, SendMessageInput, Message, SpawnApprovalMode, SpawnProvider, WorkspaceAutoMergePolicy, WorkspaceMergeStrategy, WorkspaceMode, WorkspaceRecord } from "./types";
 import { LAND_STRATEGIES, applyWorkspaceAction, waitForWorkspaceStatus, type WorkspaceAction } from "./workspace-actions";
 import { AUTO_MERGE_POLICIES } from "./workspace-merge";
@@ -460,7 +460,7 @@ const TOOLS: ToolDefinition[] = [
       additionalProperties: false,
     },
   },
-  ...TEAM_TOOLS,
+  ...MERGE_TOOLS, ...TEAM_TOOLS,
   ...PLAN_TOOLS,
   ...BLACKBOARD_TOOLS,
   ...PROJECT_TOOLS,
@@ -577,7 +577,7 @@ async function callTool(auth: McpAuthContext, params: unknown): Promise<Record<s
     else if (name === "relay_workspace_claim") result = relayWorkspaceMutation(auth, "claim", args);
     else if (name === "relay_workspace_release") result = relayWorkspaceMutation(auth, "release-claim", args);
     else if (name === "relay_workspace_land") result = relayWorkspaceMutation(auth, "merge", args);
-    else if (name.startsWith("relay_team_")) result = await relayTeamTool(auth, name, args);
+    else if (name.startsWith("relay_merge_")) result = relayMergeTool(auth, name, args); else if (name.startsWith("relay_team_")) result = await relayTeamTool(auth, name, args);
     else if (name.startsWith("relay_plan_")) result = relayPlanTool(auth, name, args);
     else if (name.startsWith("relay_blackboard_")) result = relayBlackboardTool(auth, name, args);
     else if (name.startsWith("relay_project_")) result = relayProjectTool(auth, name, args);
@@ -869,7 +869,7 @@ async function relaySpawnAgent(auth: McpAuthContext, args: Record<string, unknow
     orchestratorId: optionalString(args.orchestratorId, "orchestratorId", 200),
     cwd: optionalString(args.cwd, "cwd", 500),
     model: optionalString(args.model, "model", 120),
-    effort: optionalEnum(args.effort, "effort", VALID_EFFORTS) as ProviderEffort | undefined,
+    effort: optionalString(args.effort, "effort", 120) as ProviderEffort | undefined,
     approvalMode: optionalEnum(args.approvalMode, "approvalMode", APPROVAL_MODES) as SpawnApprovalMode | undefined,
     workspaceMode: optionalEnum(args.workspaceMode, "workspaceMode", VALID_WORKSPACE_MODES) as WorkspaceMode | undefined,
     lifecycle: (optionalEnum(args.lifecycle, "lifecycle", VALID_AGENT_LIFECYCLES) as AgentLifecycle | undefined) ?? "persistent",
@@ -1043,7 +1043,6 @@ function relayWorkspaceMutation(auth: McpAuthContext, action: WorkspaceAction, a
   return payload;
 }
 
-
 function payloadWithAttachments(
   payload: Record<string, unknown> | undefined,
   attachments: AttachmentRef[] | undefined,
@@ -1141,10 +1140,10 @@ function sniffMediaType(bytes: Uint8Array, hinted?: string, filename?: string):
 function visibleTools(auth: McpAuthContext): Array<Record<string, unknown>> {
   return TOOLS
     .filter((tool) => hasAnyScope(auth, tool.requiredScopes))
-    .map(({ name, description, inputSchema, alwaysLoad }) => ({
+    .map(({ name, description, alwaysLoad, ...tool }) => ({
       name,
       description,
-      inputSchema,
+      inputSchema: providerCatalogToolInputSchema(name, tool.inputSchema),
       ...(alwaysLoad ? { _meta: { "anthropic/alwaysLoad": true } } : {}),
     }));
 }

package/src/merge-pause-maintenance.ts

@@ -0,0 +1,13 @@
+import { REAP_INTERVAL_MS } from "./config";
+import { releaseExpiredMergePauses } from "./db";
+
+export const MERGE_PAUSE_MAINTENANCE_JOB = {
+  id: "merge-pause-expiration",
+  title: "Merge pause expiration",
+  description: "Release expired repo/base auto-merge pauses.",
+  intervalMs: REAP_INTERVAL_MS,
+  runOnStart: true,
+  handler() {
+    return { releasedMergePauseIds: releaseExpiredMergePauses() };
+  },
+};

package/src/provider-catalog-store.ts

@@ -13,6 +13,7 @@ interface ProviderModelOverrideRow {
   alias: string;
   entry: string;
   deleted: number;
+  disabled: number;
   updated_at: number;
   updated_by?: string | null;
 }
@@ -22,6 +23,7 @@ interface ProviderModelOverride {
   alias: string;
   entry: ProviderModelCatalogEntry;
   deleted: boolean;
+  disabled: boolean;
   updatedAt: number;
   updatedBy?: string;
 }
@@ -31,6 +33,7 @@ interface ProviderModelOverrideInput {
   alias: string;
   entry: ProviderModelCatalogEntry;
   deleted?: boolean;
+  disabled?: boolean;
   updatedBy?: string;
 }
 
@@ -45,11 +48,12 @@ export function upsertProviderModelOverride(input: ProviderModelOverrideInput):
   const normalized = normalizeOverrideInput(input);
   const now = Date.now();
   getDb().query(`
-    INSERT INTO provider_model_overrides (provider, alias, entry, deleted, updated_at, updated_by)
-    VALUES (?, ?, ?, ?, ?, ?)
+    INSERT INTO provider_model_overrides (provider, alias, entry, deleted, disabled, updated_at, updated_by)
+    VALUES (?, ?, ?, ?, ?, ?, ?)
     ON CONFLICT(provider, alias) DO UPDATE SET
       entry = excluded.entry,
       deleted = excluded.deleted,
+      disabled = excluded.disabled,
       updated_at = excluded.updated_at,
       updated_by = excluded.updated_by
   `).run(
@@ -57,6 +61,7 @@ export function upsertProviderModelOverride(input: ProviderModelOverrideInput):
     normalized.alias,
     JSON.stringify(normalized.entry),
     normalized.deleted ? 1 : 0,
+    normalized.disabled ? 1 : 0,
     now,
     normalized.updatedBy ?? null,
   );
@@ -66,6 +71,7 @@ export function upsertProviderModelOverride(input: ProviderModelOverrideInput):
     alias: normalized.alias,
     entry: normalized.entry,
     deleted: Boolean(normalized.deleted),
+    disabled: Boolean(normalized.disabled),
     updatedAt: now,
     updatedBy: normalized.updatedBy,
   };
@@ -83,10 +89,26 @@ export function removeProviderModelOverride(provider: SpawnProvider, alias: stri
   });
 }
 
+export function setProviderModelDisabled(provider: SpawnProvider, alias: string, disabled: boolean, updatedBy?: string): ProviderModelOverride {
+  const existing = findModelEntry(provider, alias);
+  if (!existing) throw new ValidationError(`unknown ${provider} model: ${alias}`);
+  return upsertProviderModelOverride({
+    provider,
+    alias,
+    entry: existing,
+    disabled,
+    updatedBy,
+  });
+}
+
 export function effectiveProviderCatalogList(): ProviderCatalogEntry[] {
   return mergeProviderCatalog(providerCatalogList(), listProviderModelOverrides());
 }
 
+export function effectiveProviderEffortLevels(): string[] {
+  return [...new Set(effectiveProviderCatalogList().flatMap((provider) => provider.models.flatMap((model) => model.efforts)))].sort();
+}
+
 export function mergeProviderCatalog(
   baseCatalog: ProviderCatalogEntry[],
   overrides: ProviderModelOverride[],
@@ -102,7 +124,11 @@ export function mergeProviderCatalog(
       if (existingIndex >= 0) providerEntry.models.splice(existingIndex, 1);
       continue;
     }
-    const nextEntry = cloneModelEntry({ ...override.entry, alias: override.alias });
+    const nextEntry = cloneModelEntry({
+      ...override.entry,
+      alias: override.alias,
+      ...(override.disabled ? { disabled: true } : { disabled: undefined }),
+    });
     if (existingIndex >= 0) providerEntry.models[existingIndex] = nextEntry;
     else providerEntry.models.push(nextEntry);
   }
@@ -118,10 +144,12 @@ function normalizeOverrideInput(input: ProviderModelOverrideInput): ProviderMode
   if (!input.entry.label?.trim()) throw new ValidationError("model label is required");
   if (!input.entry.providerModel?.trim()) throw new ValidationError("provider model is required");
   if (!Array.isArray(input.entry.efforts)) throw new ValidationError("model efforts must be an array");
+  const entry = cloneModelEntry({ ...input.entry, alias });
+  delete entry.disabled;
   return {
     ...input,
     alias,
-    entry: cloneModelEntry({ ...input.entry, alias }),
+    entry,
     updatedBy: input.updatedBy?.trim() || undefined,
   };
 }
@@ -134,6 +162,7 @@ function rowToOverride(row: ProviderModelOverrideRow): ProviderModelOverride | u
     alias: row.alias,
     entry: cloneModelEntry({ ...parsed, alias: row.alias }),
     deleted: row.deleted === 1,
+    disabled: row.disabled === 1,
     updatedAt: row.updated_at,
     updatedBy: row.updated_by ?? undefined,
   };

package/src/provider-config-store.ts

@@ -0,0 +1,216 @@
+import { existsSync, readdirSync } from "node:fs";
+import { hostname } from "node:os";
+import { join } from "node:path";
+import { ValidationError, listOrchestrators } from "./db";
+import { getConfig, listConfig, setConfig } from "./config-store";
+import { cleanString, cleanStringArray, optionalEnum } from "./validation";
+import { emitConfigChanged } from "./sse";
+import {
+  PROVIDER_CONFIG_NAMESPACE,
+  validateSettingValue,
+} from "./settings/registry";
+import {
+  getProviderSettingsDeclaration,
+  listProviderSettingsDeclarations,
+  providerConfigDefaults,
+  registerDeclaredProviderConfigSetting,
+} from "./settings/modules";
+import { defaultProviderConfig, loadProviderConfig as loadLocalProviderConfig } from "../runner/src/config";
+import { SPAWN_PROVIDERS, isRecord, type ConfigEntry, type SpawnProvider } from "agent-relay-sdk";
+import type { ProviderConfig } from "../runner/src/adapter";
+
+export const VALID_PROVIDER_CONFIGS = SPAWN_PROVIDERS;
+
+type ProviderConfigProvider = string;
+type ProviderConfigEntry = ConfigEntry<ProviderConfig>;
+
+export function defaultProviderConfigHost(): string {
+  return hostname();
+}
+
+export function providerConfigKey(host: string, provider: string): string {
+  return `${normalizeProviderConfigHost(host)}/${normalizeProviderConfigProvider(provider)}`;
+}
+
+export function parseProviderConfigKey(key: string): { host: string; provider: ProviderConfigProvider } | null {
+  const slash = key.lastIndexOf("/");
+  if (slash <= 0 || slash === key.length - 1) return null;
+  const host = cleanString(key.slice(0, slash), "host", { required: true, max: 120 })!;
+  const provider = cleanString(key.slice(slash + 1), "provider", { required: true, max: 80 })!;
+  return getProviderSettingsDeclaration(provider) ? { host, provider } : null;
+}
+
+export function ensureProviderConfigDescriptors(extraKeys: string[] = []): void {
+  const keys = new Set<string>();
+  const providerDeclarations = listProviderSettingsDeclarations();
+  for (const entry of listConfig(PROVIDER_CONFIG_NAMESPACE)) keys.add(entry.key);
+  for (const orchestrator of listOrchestrators()) {
+    if (!orchestrator.hostname) continue;
+    for (const declaration of providerDeclarations) keys.add(providerConfigKey(orchestrator.hostname, declaration.provider));
+  }
+  for (const declaration of providerDeclarations) keys.add(providerConfigKey(defaultProviderConfigHost(), declaration.provider));
+  for (const key of extraKeys) keys.add(key);
+
+  for (const key of keys) {
+    const parsed = parseProviderConfigKey(key);
+    if (!parsed) continue;
+    registerDeclaredProviderConfigSetting({
+      host: parsed.host,
+      provider: parsed.provider,
+    });
+  }
+}
+
+export function getProviderConfigEntry(provider: string, host = defaultProviderConfigHost()): ProviderConfigEntry {
+  const cleanProvider = normalizeProviderConfigProvider(provider);
+  const cleanHost = normalizeProviderConfigHost(host);
+  const key = providerConfigKey(cleanHost, cleanProvider);
+  ensureProviderConfigDescriptors([key]);
+  const entry = getConfig<ProviderConfig>(PROVIDER_CONFIG_NAMESPACE, key);
+  if (entry) return { ...entry, value: mergeProviderConfig(cleanProvider, entry.value) };
+  return {
+    namespace: PROVIDER_CONFIG_NAMESPACE,
+    key,
+    value: providerConfigDefaults(cleanProvider),
+    version: 0,
+    updatedAt: "default",
+    updatedBy: "system",
+  };
+}
+
+export function listProviderConfigEntries(host = defaultProviderConfigHost()): Record<SpawnProvider, ProviderConfigEntry> {
+  return Object.fromEntries(
+    VALID_PROVIDER_CONFIGS.map((provider) => [provider, getProviderConfigEntry(provider, host)]),
+  ) as Record<SpawnProvider, ProviderConfigEntry>;
+}
+
+export function setProviderConfig(
+  provider: string,
+  value: unknown,
+  opts: { host?: string; updatedBy?: string } = {},
+): ProviderConfigEntry {
+  const cleanProvider = normalizeProviderConfigProvider(provider);
+  const host = normalizeProviderConfigHost(opts.host ?? defaultProviderConfigHost());
+  const normalized = cleanProviderConfig(cleanProvider, value);
+  const key = providerConfigKey(host, cleanProvider);
+  ensureProviderConfigDescriptors([key]);
+  const validation = validateSettingValue(PROVIDER_CONFIG_NAMESPACE, key, normalized);
+  if (!validation.valid) throw new ValidationError(validation.errors.join("; "));
+  return setConfig(PROVIDER_CONFIG_NAMESPACE, key, normalized, opts.updatedBy) as ProviderConfigEntry;
+}
+
+export function providerConfigPublic(entry: ProviderConfigEntry, opts: { maskEnv?: boolean } = {}): Record<string, unknown> {
+  const parsed = parseProviderConfigKey(entry.key);
+  return {
+    namespace: entry.namespace,
+    key: entry.key,
+    path: `config:${entry.namespace}/${entry.key}`,
+    host: parsed?.host,
+    provider: parsed?.provider,
+    version: entry.version,
+    updatedAt: entry.updatedAt,
+    updatedBy: entry.updatedBy,
+    command: entry.value.command,
+    defaultArgs: entry.value.defaultArgs,
+    env: opts.maskEnv === false ? entry.value.env : maskEnv(entry.value.env),
+    pluginDirs: entry.value.pluginDirs,
+    defaultCapabilities: entry.value.defaultCapabilities,
+    defaultApprovalMode: entry.value.defaultApprovalMode,
+    defaultTags: entry.value.defaultTags,
+    chatCaptureMode: entry.value.chatCaptureMode,
+    reasoningCapture: entry.value.reasoningCapture,
+    headless: entry.value.headless,
+  };
+}
+
+export function migrateLocalProviderConfigs(home = agentRelayHome(), host = defaultProviderConfigHost()): ProviderConfigEntry[] {
+  const dir = join(home, "providers");
+  if (!existsSync(dir)) return [];
+  const migrated: ProviderConfigEntry[] = [];
+  for (const file of readdirSync(dir)) {
+    const provider = file.endsWith(".json") ? file.slice(0, -".json".length) : "";
+    if (!VALID_PROVIDER_CONFIGS.includes(provider as SpawnProvider)) continue;
+    const key = providerConfigKey(host, provider);
+    if (getConfig(PROVIDER_CONFIG_NAMESPACE, key)) continue;
+    const local = loadLocalProviderConfig(provider, home);
+    const entry = setProviderConfig(provider, local, { host, updatedBy: `migration:${host}` });
+    emitConfigChanged(entry.namespace, entry.key, entry.version);
+    migrated.push(entry);
+  }
+  return migrated;
+}
+
+function normalizeProviderConfigHost(host: string): string {
+  return cleanString(host, "host", { required: true, max: 120 })!;
+}
+
+function normalizeProviderConfigProvider(provider: string): ProviderConfigProvider {
+  const clean = cleanString(provider, "provider", { required: true, max: 80 })!;
+  if (!getProviderSettingsDeclaration(clean)) {
+    throw new ValidationError(`provider must be one of: ${listProviderSettingsDeclarations().map((d) => d.provider).join(", ")}`);
+  }
+  return clean;
+}
+
+function cleanProviderConfig(provider: string, value: unknown): ProviderConfig {
+  if (!isRecord(value)) throw new ValidationError("provider config body must be an object");
+  const defaults = providerConfigDefaults(provider);
+  const headless = isRecord(value.headless) ? value.headless : {};
+  return {
+    command: cleanString(value.command, "command", { required: true, max: 500 })!,
+    defaultArgs: cleanStringArray(value.defaultArgs, "defaultArgs", { itemMax: 80, maxItems: 50 }) ?? defaults.defaultArgs,
+    env: cleanEnvRecord(value.env),
+    pluginDirs: cleanStringArray(value.pluginDirs, "pluginDirs", { itemMax: 80, maxItems: 50 }) ?? defaults.pluginDirs,
+    defaultCapabilities: cleanStringArray(value.defaultCapabilities, "defaultCapabilities", { itemMax: 80, maxItems: 50 }) ?? defaults.defaultCapabilities,
+    defaultApprovalMode: cleanString(value.defaultApprovalMode, "defaultApprovalMode", { max: 80 }) ?? defaults.defaultApprovalMode,
+    defaultTags: cleanStringArray(value.defaultTags, "defaultTags", { itemMax: 80, maxItems: 50 }) ?? defaults.defaultTags,
+    chatCaptureMode: (optionalEnum(value.chatCaptureMode, "chatCaptureMode", ["final", "full"]) ?? defaults.chatCaptureMode) as "final" | "full",
+    reasoningCapture: value.reasoningCapture === undefined ? defaults.reasoningCapture ?? true : cleanBoolean(value.reasoningCapture, "reasoningCapture"),
+    headless: {
+      tmuxPrefix: cleanString(headless.tmuxPrefix, "headless.tmuxPrefix", { max: 120 }) ?? defaults.headless.tmuxPrefix,
+      shutdownTimeoutMs: cleanPositiveInt(headless.shutdownTimeoutMs, "headless.shutdownTimeoutMs") ?? defaults.headless.shutdownTimeoutMs,
+    },
+  };
+}
+
+function mergeProviderConfig(provider: string, value: Partial<ProviderConfig>): ProviderConfig {
+  const defaults = providerConfigDefaults(provider);
+  return cleanProviderConfig(provider, { ...defaults, ...value, headless: { ...defaults.headless, ...value.headless } });
+}
+
+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)) {
+    const cleanKey = cleanString(key, "env key", { required: true, max: 120 })!;
+    if (typeof item !== "string") throw new ValidationError(`env.${cleanKey} must be a string`);
+    env[cleanKey] = item;
+  }
+  return env;
+}
+
+function cleanBoolean(value: unknown, field: string): boolean {
+  if (typeof value !== "boolean") throw new ValidationError(`${field} must be a boolean`);
+  return value;
+}
+
+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`);
+  }
+  return value;
+}
+
+function maskEnv(env: Record<string, string>): Record<string, string> {
+  const result: Record<string, string> = {};
+  for (const [key, value] of Object.entries(env)) {
+    result[key] = /token|secret|key|password/i.test(key) && !value.startsWith("$env:") ? "********" : value;
+  }
+  return result;
+}
+
+function agentRelayHome(): string {
+  return process.env.AGENT_RELAY_HOME || join(process.env.HOME || ".", ".agent-relay");
+}

package/src/recipe-runner.ts

@@ -2,6 +2,7 @@ import { createCommand } from "./commands-db";
 import { listOrchestrators } from "./db";
 import { resolveProviderSelection } from "agent-relay-sdk/provider-catalog";
 import { getRecipe } from "./recipe-loader";
+import { effectiveProviderCatalogList } from "./provider-catalog-store";
 import {
   createRecipeInstance,
   getRecipeInstance,
@@ -56,7 +57,7 @@ export function startRecipe(input: StartRecipeInput): StartRecipeResult {
   for (const agent of recipe.agents) {
     const count = agent.count ?? 1;
     for (let index = 0; index < count; index++) {
-      const selection = resolveProviderSelection({ provider: agent.provider, model: agent.model, effort: agent.effort });
+      const selection = resolveProviderSelection({ provider: agent.provider, model: agent.model, effort: agent.effort }, effectiveProviderCatalogList());
       const label = count > 1 ? `${recipe.name}:${agent.role}:${index + 1}` : `${recipe.name}:${agent.role}`;
       const memoryTags = [...new Set([...(recipe.lifecycle?.memory?.memoryTags ?? []), ...(agent.memoryTags ?? [])])];
       const alwaysReload = recipe.lifecycle?.memory?.alwaysReload ?? [];

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/agent-sessions.ts

@@ -1,6 +1,6 @@
 // Auto-split from routes.ts (#299). Domain: agent-sessions.
 import { RELAY_TOKEN_HEADER, isRecord } from "agent-relay-sdk";
-import { VALID_AGENT_ACTIONS, agentControlActionIcon, auditEvent, authAuditMetadata, authorizeRoute, dashboardAttribution, emitCommand, error, json, metaString, parseBody, spawnRequestId, type AgentControlAction, type Handler } from "./_shared";
+import { VALID_AGENT_ACTIONS, agentControlActionIcon, auditEvent, authAuditMetadata, authorizeRoute, cleanAttachmentRefs, dashboardAttribution, emitCommand, error, json, metaString, parseBody, spawnRequestId, type AgentControlAction, type Handler } from "./_shared";
 import { ValidationError, getAgent, getAgentTimeline, getOrchestrator, markReady, mergeAgentMeta, sendMessage } from "../db";
 import { buildManagedSpawnParams } from "../managed-policy";
 import { buildSpawnCommand, generateSpawnRequestId, resolveSpawnModelParams } from "../spawn-command";
@@ -306,6 +306,7 @@ export const postAgentPrompt: Handler = async (req, params) => {
   try {
     if (!isRecord(parsed.body)) return error("body required");
     const body = cleanString(parsed.body.body, "body", { required: true, max: 100_000 })!;
+    const attachments = cleanAttachmentRefs(parsed.body.attachments ?? parsed.body.artifacts, "attachments");
     const agent = getAgent(params.id!);
     if (!agent) return error("agent not found", 404);
     if (agent.status === "offline") return error("agent is offline", 422);
@@ -319,12 +320,13 @@ export const postAgentPrompt: Handler = async (req, params) => {
       to: agent.id,
       kind: "session",
       body,
+      ...(attachments ? { payload: { attachments } } : {}),
     });
     const command = createCommand({
       type: "prompt.inject",
       source: "dashboard",
       target: agent.id,
-      params: { body, messageId: message.id },
+      params: { body, messageId: message.id, ...(attachments ? { attachments } : {}) },
     });
     emitCommand(command);
     emitNewMessage(message);

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

@@ -315,6 +315,26 @@ export const patchCommand: Handler = async (req, params) => {
         });
       }
     }
+    if (command.type === "workspace.pr-refresh") {
+      const resultWorkspaceId = isRecord(command.result) ? cleanString(command.result.workspaceId, "result.workspaceId", { max: 160 }) : undefined;
+      const workspaceId = resultWorkspaceId ?? command.correlationId;
+      if (workspaceId && command.status === "succeeded" && isRecord(command.result) && command.result.prRefreshed === true) {
+        patchWorkspaceMetadata(workspaceId, {
+          prRefreshCommandId: command.id,
+          prRefreshedAt: Date.now(),
+          prRefreshResult: command.result,
+          prRefreshError: undefined,
+          prRefreshFailedAt: undefined,
+        });
+      } else if (workspaceId && (command.status === "failed" || command.status === "timed_out" || command.status === "rejected" || command.status === "canceled")) {
+        patchWorkspaceMetadata(workspaceId, {
+          prRefreshCommandId: command.id,
+          prRefreshError: command.error ?? "PR branch refresh failed",
+          prRefreshFailedAt: Date.now(),
+          prRefreshResult: command.result,
+        });
+      }
+    }
     if (command.type === "workspace.deps-refresh" && command.status === "succeeded" && isRecord(command.result)) {
       // Record the outcome on the row without touching status (#51) — observability
       // for the dashboard; the CLI reads the result straight off the command.