agent-relay-server 0.97.0 → 0.98.1

package/src/db/provider-quotas.ts

@@ -10,6 +10,7 @@ const PROVIDER_QUOTA_STALE_AFTER_MS = 10 * 60_000;
 const QUOTA_UTILIZATION_EPSILON = 1e-9;
 const QUOTA_RESET_BOUNDARY_ADVANCE_MS = 5_000;
 const QUOTA_RESET_UTILIZATION_MAX = 0.01;
+const FIVE_HOUR_MS = 5 * 60 * 60_000;
 
 export interface ProviderQuotaAdvisoryInput {
   provider: string;
@@ -258,11 +259,20 @@ function quotaWindowUtilizationRegressed(existing: QuotaState["windows"][number]
     && !quotaWindowLooksReset(existing, incoming);
 }
 
-function publicQuotaState(quota: StoredQuotaState): QuotaState {
+function publicQuotaState(quota: StoredQuotaState, now?: number): QuotaState {
+  let emulated = false;
+  const windows = quota.windows.map((window) => {
+    const period = quotaWindowPeriodMs(window.name);
+    if (now === undefined || period === undefined || typeof window.resetsAt !== "number" || !Number.isFinite(window.resetsAt) || now < window.resetsAt) return { ...window };
+    let resetsAt = window.resetsAt;
+    while (now >= resetsAt) resetsAt += period;
+    emulated = true;
+    return { ...window, utilization: 0, resetsAt };
+  });
   return {
-    windows: quota.windows.map((window) => ({ ...window })),
-    source: quota.source,
-    updatedAt: quota.updatedAt,
+    windows,
+    source: emulated ? "emulated" : quota.source,
+    updatedAt: emulated && now !== undefined ? Math.max(quota.updatedAt, now) : quota.updatedAt,
   };
 }
 
@@ -287,7 +297,7 @@ function storedQuotaWindowSampleTimes(quota: StoredQuotaState): Map<string, numb
 }
 
 // Source priority for per-window precedence: "ingest" (WHAM/API) beats "probe" (agent self-report).
-const QUOTA_SOURCE_PRIORITY: Record<string, number> = { ingest: 3, header: 2, probe: 1, statusline: 0 };
+const QUOTA_SOURCE_PRIORITY: Record<string, number> = { ingest: 3, header: 2, probe: 1, statusline: 0, emulated: -1 };
 function quotaSourcePriority(source: string): number {
   return QUOTA_SOURCE_PRIORITY[source] ?? 1;
 }
@@ -345,6 +355,12 @@ function quotaWindowSampleTimes(provider: string, accountKey: string, fallback?:
   return times;
 }
 
+function quotaWindowPeriodMs(name: string): number | undefined {
+  if (name === "five_hour" || name === "primary") return FIVE_HOUR_MS;
+  if (name === "seven_day" || name === "seven_day_sonnet" || name === "seven_day_opus" || name === "secondary") return 7 * DAY_MS;
+  return undefined;
+}
+
 function mergeQuotaWindows(existing: StoredQuotaState | undefined, incoming: QuotaState, provider: string, accountKey: string): {
   quota: StoredQuotaState;
   acceptedIncomingWindow: boolean;
@@ -370,12 +386,11 @@ function mergeQuotaWindows(existing: StoredQuotaState | undefined, incoming: Quo
     if (!incomingWindow) {
       mergedTimes.set(key, existingUpdatedAt); mergedSources.set(key, existingSource); return window;
     }
-    // Per-window source precedence is symmetric in BOTH directions (#712, #716):
-    // - A higher-priority existing value is kept even against a newer lower-priority reading.
-    // - A higher-priority incoming value (e.g. authoritative WHAM `ingest`) overrides the stored
-    //   value outright, bypassing the timestamp + regression guards below. Those guards exist to
-    //   reject a noisy lower-or-equal source's improbable swing (a wedged probe self-report) — they
-    //   must NOT block authoritative data correcting a stale probe that pinned the window high.
+    // Per-window source precedence: #712/#716 are handled by the symmetric three-way split below.
+    // Higher existing → keep (no regression check needed; lower-priority input simply loses).
+    // Higher incoming → accept (no regression check needed; higher-priority source is authoritative).
+    // Same priority  → apply the regression guard (rejects improbable utilization drops from noisy
+    //                  same-quality sources, e.g. a wedged probe self-report; #725 §4.3).
     const existingPriority = quotaSourcePriority(existingSource);
     const incomingPriority = quotaSourcePriority(incoming.source);
     if (existingPriority > incomingPriority) {
@@ -435,7 +450,7 @@ function rowToSnapshot(row: ProviderQuotaSnapshotRow): ProviderQuotaSnapshot {
 function rowToRecord(row: ProviderQuotaRow, history: ProviderQuotaSnapshot[], now: number): ProviderQuotaRecord {
   const lastError = parseJson<ProviderQuotaError | undefined>(row.last_error, undefined);
   const lastUpdatedAt = row.last_updated_at ?? undefined;
-  const quota = row.quota_state ? publicQuotaState(parseStoredQuotaState(row.quota_state, { windows: [], source: "probe", updatedAt: lastUpdatedAt ?? row.last_attempt_at })) : undefined;
+  const quota = row.quota_state ? publicQuotaState(parseStoredQuotaState(row.quota_state, { windows: [], source: "probe", updatedAt: lastUpdatedAt ?? row.last_attempt_at }), now) : undefined;
   const burn = quota ? deriveProviderQuotaBurn({
     provider: row.provider,
     quota,

package/src/lifecycle-manager.ts

@@ -622,8 +622,10 @@ export function __resetLifecycleManager(): void {
   singleton = null;
 }
 
-function managedModelUnavailableMessage(policy: SpawnPolicy, error: string, exited?: ManagedSessionExitDiagnostics): string | null {
-  if (policy.provider !== "claude" && exited?.provider !== "claude") return null;
+function managedModelUnavailableMessage(_policy: SpawnPolicy, error: string, exited?: ManagedSessionExitDiagnostics): string | null {
+  // extractClaudeModelUnavailableMessage returns null for text that doesn't match
+  // the Claude-specific error pattern, so this is safe to call unconditionally —
+  // no provider=== branch needed here; the parser is the gate (#743).
   return extractClaudeModelUnavailableMessage([
     error,
     exited?.lastError,

package/src/maintenance/jobs.ts

@@ -83,7 +83,7 @@ function isManagedBusyWatchCandidate(agent: ReturnType<typeof listAgents>[number
 
 function stuckBusyBody(agentId: string, health: NonNullable<ReturnType<typeof deriveAgentBusyHealth>>): string {
   const staleMinutes = Math.max(1, Math.floor(health.staleForMs / 60_000));
-  const work = health.activeWorkLabel || health.activeWorkKind || health.activeWorkId || health.kind;
+  const work = health.activeWorkLabel || health.activeWorkId || health.kind;
   return `Agent \`${agentId}\` appears stuck busy in ${work} for ${staleMinutes} min with no provider progress. Use interrupt first if available; restart or shutdown if the turn is wedged.`;
 }
 

package/src/notification-types.ts

@@ -25,7 +25,8 @@ export type NotificationType =
   | "workspace.stranded_escalation"
   | "workspace.auto_abandoned"
   | "workspace.review_request"
-  | "workspace.review_changes_requested";
+  | "workspace.review_changes_requested"
+  | "routing.policy.changed";
 
 /**
  * The entities a notification is ABOUT: routing inputs (#442) and explainability subjects (#446).
@@ -94,6 +95,7 @@ export const DEFAULT_TTL_MS: Record<NotificationType, number | null> = {
   "workspace.auto_abandoned": null,
   "workspace.review_request": null,
   "workspace.review_changes_requested": null,
+  "routing.policy.changed": 15 * MINUTES,
 };
 
 export const NOTIFICATION_TYPES = Object.keys(DEFAULT_TTL_MS) as NotificationType[];

package/src/quota.ts

@@ -1,7 +1,7 @@
 import { isRecord } from "agent-relay-sdk";
 import type { ProviderQuotaError, QuotaState, QuotaWindowName, QuotaSource, QuotaUnit } from "./types";
 
-const QUOTA_SOURCES = new Set<QuotaSource>(["header", "probe", "ingest", "statusline"]);
+const QUOTA_SOURCES = new Set<QuotaSource>(["header", "probe", "ingest", "statusline", "emulated"]);
 const QUOTA_UNITS = new Set<QuotaUnit>(["tokens", "requests", "%"]);
 const QUOTA_WINDOWS = new Set<QuotaWindowName>(["five_hour", "seven_day", "seven_day_sonnet", "seven_day_opus", "primary", "secondary"]);
 

package/src/routes/index.ts

@@ -8,6 +8,7 @@ import { deleteAutomationById, getAutomationById, getAutomationRuns, getAutomati
 import { deleteCommandById, deleteProviderModelRoute, getProviderConfigRoute, getProviderConfigsRoute, getProvidersRoute, patchProviderModelRoute, postProviderConfigTestRoute, putProviderConfigRoute, putProviderModelRoute } from "./provider-config";
 import { getProviderQuotasRoute, postProviderQuotaLeaseAcquireRoute, postProviderQuotaLeaseReleaseRoute, postProviderQuotaPublisherLeaseAcquireRoute, postProviderQuotaPublisherLeaseReleaseRoute, postProviderQuotaRoute } from "./provider-quotas";
 import { getProviderQuotaConfigRoute, getProviderQuotaConfigsRoute, putProviderQuotaConfigRoute } from "./provider-quota-config";
+import { getRoutingPolicyRoute, putRoutingPolicyRoute } from "./routing-policy";
 import { deleteProvisioningCapabilityRoute, getProvisioningCapabilitiesRoute, getProvisioningCapabilityRoute, patchProvisioningCapabilityRoute, patchProvisioningVariantRoute, postProvisioningCapabilityRoute, postProvisioningVariantImportRoute, postProvisioningVariantMcpRoute, postProvisioningVariantUpdateRoute, postProvisioningVariantValidateRoute } from "./provisioning-registry";
 import { getTeamsConfigRoute, putTeamsConfigRoute } from "./teams-config";
 import { deleteConfigKey, getConfigKey, getConfigKeyHistory, getConfigNamespace, putConfigKey } from "./config";
@@ -281,6 +282,8 @@ const routes: Route[] = [
   route("GET", "/api/providers/quota-config", getProviderQuotaConfigsRoute),
   route("GET", "/api/providers/:provider/quota-config", getProviderQuotaConfigRoute),
   route("PUT", "/api/providers/:provider/quota-config", putProviderQuotaConfigRoute),
+  route("GET", "/api/routing-policy", getRoutingPolicyRoute),
+  route("PUT", "/api/routing-policy", putRoutingPolicyRoute),
   route("PUT", "/api/providers/:provider/models/:alias", putProviderModelRoute),
   route("PATCH", "/api/providers/:provider/models/:alias", patchProviderModelRoute),
   route("DELETE", "/api/providers/:provider/models/:alias", deleteProviderModelRoute),

package/src/routes/routing-policy.ts

@@ -0,0 +1,25 @@
+// Routing-policy routes (#728). GET/PUT for the relay-owned routing-policy document.
+// GET: agent:read (coordinators read the policy to apply rules).
+// PUT: settings:write:routing (admin writes).
+import { ValidationError } from "../db";
+import { error, json, parseBody, type Handler } from "./_shared";
+import { getRoutingPolicy, setRoutingPolicy } from "../routing-policy-store";
+import { isRecord } from "agent-relay-sdk";
+import { cleanString } from "../validation";
+
+export const getRoutingPolicyRoute: Handler = () => {
+  return json(getRoutingPolicy());
+};
+
+export const putRoutingPolicyRoute: Handler = async (req) => {
+  const parsed = await parseBody<unknown>(req);
+  if (!parsed.ok) return error(parsed.error, parsed.status);
+  try {
+    const updatedBy = isRecord(parsed.body) ? cleanString(parsed.body.updatedBy, "updatedBy", { max: 200 }) : undefined;
+    const policy = setRoutingPolicy(parsed.body, { updatedBy });
+    return json(policy);
+  } catch (e) {
+    if (e instanceof ValidationError) return error(e.message, 400);
+    throw e;
+  }
+};

package/src/routing-policy-push.ts

@@ -0,0 +1,82 @@
+// Live delta push for routing-policy saves (#732). When the policy is updated via
+// PUT /api/routing-policy, all live spawn-capable agents (coordinators) receive an
+// in-band routing.policy.changed notification so the change takes effect mid-session
+// without respawn.
+//
+// Delivery mechanism: same emitRelayEvent + routeNotification path as agent.ready /
+// agent.exited (#308/#239). emitRelayEvent writes to the durable bus outbox (so bus
+// clients subscribed to routing.* receive it immediately); routeNotification sends a
+// message.new push to each spawn-capable agent's inbox so connected coordinators
+// that are subscribed only to message.* are also woken with the delta in-band.
+//
+// Spawn-capable = live token carries command:spawn (or command:* / admin:* / *).
+// The same token-scope check used by quota-advisory.ts (isSpawnCapableAgent).
+import { getDb } from "./db";
+import { emitRelayEvent } from "./events";
+import { routeNotification } from "./notification-router";
+import { parseJson } from "./utils";
+import { isRecord } from "agent-relay-sdk";
+import type { RoutingPolicy } from "agent-relay-sdk";
+
+const PUSH_TTL_MS = 15 * 60 * 1000;
+
+/**
+ * Emit a durable `routing.policy.changed` event and push the delta to every
+ * live spawn-capable agent so coordinators ingest the new policy mid-session.
+ * Called by setRoutingPolicy on every successful save.
+ */
+export function notifyRoutingPolicyChanged(policy: RoutingPolicy, opts: { updatedBy?: string } = {}): void {
+  emitRelayEvent({
+    type: "routing.policy.changed",
+    source: "server",
+    subject: "routing-policy:default",
+    data: { policy: policy as unknown as Record<string, unknown>, updatedBy: opts.updatedBy ?? null },
+  });
+
+  const recipients = getSpawnCapableAgentIds();
+  if (recipients.length === 0) return;
+
+  routeNotification({
+    type: "routing.policy.changed",
+    scope: {},
+    recipients,
+    ttlMs: PUSH_TTL_MS,
+    message: {
+      subject: "Routing policy updated",
+      body: `🗺 Routing policy updated${opts.updatedBy ? ` by ${opts.updatedBy}` : ""}. Ingest this delta now — spawn routing decisions take effect immediately without respawn. Re-read relay_spawn_targets for live provider/model options.`,
+      payload: { kind: "routing.policy.changed", policy: policy as unknown as Record<string, unknown>, updatedBy: opts.updatedBy ?? null },
+      replyExpected: false,
+    },
+  });
+}
+
+type AgentRow = { id: string; meta: string | null };
+
+function getSpawnCapableAgentIds(): string[] {
+  const now = Date.now();
+  const candidates = getDb().query(`
+    SELECT id, meta FROM agents
+    WHERE ready = 1 AND status NOT IN ('offline', 'stale')
+  `).all() as AgentRow[];
+  return candidates.filter((agent) => isSpawnCapable(agent, now)).map((a) => a.id);
+}
+
+function isSpawnCapable(agent: AgentRow, now: number): boolean {
+  const meta = parseJson<Record<string, unknown>>(agent.meta ?? "{}", {});
+  const auth = isRecord(meta.auth) ? meta.auth : undefined;
+  const jti = typeof auth?.jti === "string" ? auth.jti : undefined;
+  if (!jti) return false;
+  const row = getDb().query(
+    "SELECT scope, revoked_at, expires_at FROM tokens WHERE jti = ?",
+  ).get(jti) as { scope: string; revoked_at?: number | null; expires_at?: number | null } | undefined;
+  if (!row || row.revoked_at) return false;
+  const nowSeconds = Math.floor(now / 1000);
+  if (row.expires_at !== null && row.expires_at !== undefined && row.expires_at <= nowSeconds) return false;
+  const scopes = parseJson<string[]>(row.scope, []);
+  return (
+    scopes.includes("command:spawn") ||
+    scopes.includes("command:*") ||
+    scopes.includes("admin:*") ||
+    scopes.includes("*")
+  );
+}

package/src/routing-policy-store.ts

@@ -0,0 +1,148 @@
+// Routing-policy storage (#728). One relay-owned policy document per instance,
+// backed by the existing `config` table (namespace "routing-policy", key "default")
+// so history + config.changed SSE come for free at no schema cost.
+//
+// The policy covers routing rules (task-type/capability → provider/model/effort)
+// and quota tuning (band thresholds + per-provider hardBackstopUtilization /
+// burnPenaltyUtilizationFloor). #730 will wire quota fields into spawn-targets.ts;
+// this module only stores and retrieves them.
+import { ValidationError } from "./db";
+import { getConfig, setConfig } from "./config-store";
+import { notifyRoutingPolicyChanged } from "./routing-policy-push";
+import { isRecord, SPAWN_PROVIDERS } from "agent-relay-sdk";
+import type { ProviderQuotaRoutingConfig, QuotaBandThresholds, RoutingPolicy, RoutingRule } from "agent-relay-sdk";
+
+export const ROUTING_POLICY_NAMESPACE = "routing-policy";
+export const ROUTING_POLICY_KEY = "default";
+
+/** Default policy — preserves current spawn-targets.ts behaviour when unset. */
+export const DEFAULT_ROUTING_POLICY: RoutingPolicy = {
+  schemaVersion: 1,
+  rules: [],
+};
+
+/** Retrieve the stored routing policy, falling back to the default when absent. */
+export function getRoutingPolicy(): RoutingPolicy {
+  const entry = getConfig<RoutingPolicy>(ROUTING_POLICY_NAMESPACE, ROUTING_POLICY_KEY);
+  return entry ? normalizeRoutingPolicy(entry.value) : { ...DEFAULT_ROUTING_POLICY };
+}
+
+/**
+ * Persist the routing policy. The incoming value is normalized so partial bodies
+ * still produce a valid document. Emits `config.changed` via `setConfig` so the
+ * dashboard + any live listeners pick it up immediately.
+ */
+export function setRoutingPolicy(value: unknown, opts: { updatedBy?: string } = {}): RoutingPolicy {
+  const normalized = normalizeRoutingPolicy(value);
+  setConfig(ROUTING_POLICY_NAMESPACE, ROUTING_POLICY_KEY, normalized, opts.updatedBy);
+  notifyRoutingPolicyChanged(normalized, opts);
+  return normalized;
+}
+
+// ---------------------------------------------------------------------------
+// Normalizer — coerces arbitrary input into a valid RoutingPolicy, defaulting
+// missing fields so a partial PUT is safe and a missing policy is a no-op.
+// ---------------------------------------------------------------------------
+
+export function normalizeRoutingPolicy(value: unknown): RoutingPolicy {
+  const input = isRecord(value) ? value : {};
+  return {
+    schemaVersion: 1,
+    rules: normalizeRules(input.rules),
+    ...(input.quotaBands !== undefined ? { quotaBands: normalizeQuotaBands(input.quotaBands) } : {}),
+    ...(input.providerQuota !== undefined ? { providerQuota: normalizeProviderQuota(input.providerQuota) } : {}),
+  };
+}
+
+function normalizeRules(raw: unknown): RoutingRule[] {
+  if (!Array.isArray(raw)) return [];
+  const rules: RoutingRule[] = [];
+  for (let i = 0; i < raw.length; i++) {
+    rules.push(normalizeRule(raw[i], i));
+  }
+  return rules;
+}
+
+function normalizeRule(raw: unknown, idx: number): RoutingRule {
+  if (!isRecord(raw)) throw new ValidationError(`rules[${idx}] must be an object`);
+  const match = isRecord(raw.match) ? raw.match : {};
+  if (!isRecord(raw.match)) throw new ValidationError(`rules[${idx}].match must be an object`);
+  if (match.taskType === undefined && match.capability === undefined) {
+    throw new ValidationError(`rules[${idx}].match must set at least one of: taskType, capability`);
+  }
+  const target = isRecord(raw.target) ? raw.target : {};
+  if (!isRecord(raw.target)) throw new ValidationError(`rules[${idx}].target must be an object`);
+  if (typeof target.provider !== "string" || !(SPAWN_PROVIDERS as readonly string[]).includes(target.provider)) {
+    throw new ValidationError(`rules[${idx}].target.provider must be one of: ${SPAWN_PROVIDERS.join(", ")}`);
+  }
+  const rule: RoutingRule = {
+    match: {
+      ...(typeof match.taskType === "string" && match.taskType ? { taskType: match.taskType } : {}),
+      ...(typeof match.capability === "string" && match.capability ? { capability: match.capability } : {}),
+    },
+    target: {
+      provider: target.provider as RoutingRule["target"]["provider"],
+      ...(typeof target.model === "string" && target.model ? { model: target.model } : {}),
+      ...(typeof target.effort === "string" && target.effort ? { effort: target.effort } : {}),
+    },
+  };
+  if (typeof raw.label === "string" && raw.label) rule.label = raw.label;
+  if (typeof raw.enabled === "boolean") rule.enabled = raw.enabled;
+  return rule;
+}
+
+function normalizeQuotaBands(raw: unknown): Partial<QuotaBandThresholds> {
+  if (!isRecord(raw)) throw new ValidationError("quotaBands must be an object");
+  const result: Partial<QuotaBandThresholds> = {};
+  if (raw.cautionAt !== undefined) result.cautionAt = cleanQuotaFraction(raw.cautionAt, "quotaBands.cautionAt");
+  if (raw.avoidLargeAt !== undefined) result.avoidLargeAt = cleanQuotaFraction(raw.avoidLargeAt, "quotaBands.avoidLargeAt");
+  if (raw.hardAvoidAt !== undefined) result.hardAvoidAt = cleanQuotaFraction(raw.hardAvoidAt, "quotaBands.hardAvoidAt");
+  const orderedPairs: Array<[string, number]> = [];
+  if (result.cautionAt !== undefined) orderedPairs.push(["cautionAt", result.cautionAt]);
+  if (result.avoidLargeAt !== undefined) orderedPairs.push(["avoidLargeAt", result.avoidLargeAt]);
+  if (result.hardAvoidAt !== undefined) orderedPairs.push(["hardAvoidAt", result.hardAvoidAt]);
+  for (let i = 0; i < orderedPairs.length - 1; i++) {
+    const cur = orderedPairs[i]!;
+    const next = orderedPairs[i + 1]!;
+    if (cur[1] >= next[1]) {
+      throw new ValidationError(`quotaBands.${cur[0]} must be less than quotaBands.${next[0]}`);
+    }
+  }
+  return result;
+}
+
+function normalizeProviderQuota(raw: unknown): Partial<Record<string, ProviderQuotaRoutingConfig>> {
+  if (!isRecord(raw)) throw new ValidationError("providerQuota must be an object");
+  const result: Partial<Record<string, ProviderQuotaRoutingConfig>> = {};
+  for (const provider of SPAWN_PROVIDERS) {
+    if (!(provider in raw)) continue;
+    result[provider] = normalizeProviderQuotaConfig(raw[provider], provider);
+  }
+  return result;
+}
+
+function normalizeProviderQuotaConfig(raw: unknown, provider: string): ProviderQuotaRoutingConfig {
+  if (!isRecord(raw)) throw new ValidationError(`providerQuota.${provider} must be an object`);
+  const cfg: ProviderQuotaRoutingConfig = {};
+  if (raw.hardBackstopUtilization !== undefined) {
+    cfg.hardBackstopUtilization = cleanFraction(raw.hardBackstopUtilization, `providerQuota.${provider}.hardBackstopUtilization`);
+  }
+  if (raw.burnPenaltyUtilizationFloor !== undefined) {
+    cfg.burnPenaltyUtilizationFloor = cleanFraction(raw.burnPenaltyUtilizationFloor, `providerQuota.${provider}.burnPenaltyUtilizationFloor`);
+  }
+  return cfg;
+}
+
+function cleanQuotaFraction(value: unknown, field: string): number {
+  if (typeof value !== "number" || !Number.isFinite(value) || value < 0) {
+    throw new ValidationError(`${field} must be a non-negative finite number`);
+  }
+  return value;
+}
+
+function cleanFraction(value: unknown, field: string): number {
+  if (typeof value !== "number" || !Number.isFinite(value) || value < 0 || value > 1) {
+    throw new ValidationError(`${field} must be a number between 0 and 1`);
+  }
+  return value;
+}

package/src/routing-rule-resolver.ts

@@ -0,0 +1,87 @@
+// Declarative routing-rules engine (#729).
+//
+// Resolves the first matching enabled rule from RoutingPolicy.rules, given a task-type
+// and/or capability. Rules are ADVISORY — they surface a recommended target to the
+// coordinator; they never override an explicit per-spawn argument or block a spawn.
+//
+// Precedence (highest → lowest):
+//  1. Explicit per-spawn args (provider/model/effort in relay_spawn_agent / SpawnAgentInput).
+//  2. This resolver — the recommendation when no explicit arg is given.
+//  3. Profile default — fallback when no rule matches.
+//
+// The quota band / gate is a parallel SAFETY layer that composes on top of the resolved
+// target (it may advise a cheaper effort or healthier provider; a hard block still blocks).
+// It is NOT part of rule resolution and is NOT consulted here.
+import type { RoutingRule } from "agent-relay-sdk";
+
+/** Input criteria for rule matching. At least one field should be set. */
+export interface RoutingMatchInput {
+  /** Task-type to match against rule.match.taskType (prefix semantics). */
+  taskType?: string;
+  /** Capability tag to match against rule.match.capability (exact match). */
+  capability?: string;
+}
+
+/**
+ * The resolved target recommendation from a matching rule.
+ * Mirrors RoutingRule["target"] so callers never import the full rule.
+ */
+export interface RoutingResolution {
+  /** Recommended provider. */
+  provider: RoutingRule["target"]["provider"];
+  /** Recommended model alias, if the rule specifies one. */
+  model?: string;
+  /** Recommended effort level, if the rule specifies one. */
+  effort?: string;
+  /** Human-readable label from the matched rule, for logging/display. */
+  matchedRuleLabel?: string;
+}
+
+/**
+ * Evaluate the rules array in order and return the first matching enabled rule's target.
+ *
+ * Match semantics:
+ * - `taskType`: the rule's taskType is a prefix of the input (e.g. rule "gui" matches
+ *   input "gui" and "gui/ux", but not "gui2" or "xgui"). Case-sensitive.
+ * - `capability`: exact match. Case-sensitive.
+ * - When a rule sets both taskType AND capability, both must match (AND semantics).
+ * - A rule with `enabled: false` is skipped.
+ *
+ * Returns null when no rule matches or the rules array is empty.
+ */
+export function resolveRoutingRule(
+  rules: RoutingRule[],
+  input: RoutingMatchInput,
+): RoutingResolution | null {
+  for (const rule of rules) {
+    if (rule.enabled === false) continue;
+    if (!matchesCriteria(rule.match, input)) continue;
+    return {
+      provider: rule.target.provider,
+      ...(rule.target.model ? { model: rule.target.model } : {}),
+      ...(rule.target.effort ? { effort: rule.target.effort } : {}),
+      ...(rule.label ? { matchedRuleLabel: rule.label } : {}),
+    };
+  }
+  return null;
+}
+
+function matchesCriteria(criteria: RoutingRule["match"], input: RoutingMatchInput): boolean {
+  if (!criteria.taskType && !criteria.capability) return false;
+  if (criteria.taskType !== undefined) {
+    if (!input.taskType) return false;
+    if (!isPrefixMatch(input.taskType, criteria.taskType)) return false;
+  }
+  if (criteria.capability !== undefined) {
+    if (input.capability !== criteria.capability) return false;
+  }
+  return true;
+}
+
+/**
+ * True if `value` equals `prefix` or starts with `prefix + "/"`.
+ * Guards against substring-only matches (e.g. "gui" must not match "gui2").
+ */
+function isPrefixMatch(value: string, prefix: string): boolean {
+  return value === prefix || value.startsWith(prefix + "/");
+}

package/src/security.ts

@@ -199,6 +199,7 @@ export function requiredScopeFor(method: string, pathname: string): string | nul
   if (pathname.startsWith("/api/pairs")) return method === "GET" ? "pairs:read" : "pairs:write";
   if (pathname === "/api/provider-quota-leases/acquire" || pathname === "/api/provider-quota-leases/release") return "quota:write";
   if (pathname === "/api/provider-quotas") return method === "GET" ? "agent:read" : "quota:write";
+  if (pathname === "/api/routing-policy") return method === "GET" ? "agent:read" : "settings:write:routing";
   if (pathname === "/api/teams/config") return method === "GET" ? "teams:read" : "settings:write:teams";
   if (pathname.startsWith("/api/teams")) return method === "GET" ? "teams:read" : "teams:write";
   if (pathname.startsWith("/api/blackboard")) return method === "GET" ? "blackboard:read" : "blackboard:write";
@@ -288,6 +289,11 @@ export function requiredComponentScopeFor(method: string, pathname: string): str
   if (pathname === "/api/providers/quota-config" || pathname.match(/^\/api\/providers\/[^/]+\/quota-config$/)) {
     return method === "GET" ? "agent:read" : "settings:write:provider";
   }
+  // Routing policy (#728): reads are agent:read (coordinators read to apply rules);
+  // writes are settings:write:routing (admin-scoped).
+  if (pathname === "/api/routing-policy") {
+    return method === "GET" ? "agent:read" : "settings:write:routing";
+  }
   if (pathname === "/api/teams/config") return method === "GET" ? "teams:read" : "settings:write:teams";
   if (pathname.startsWith("/api/messages") || pathname.startsWith("/api/inbox")) return method === "GET" ? "message:read" : "message:send";
   if (pathname.startsWith("/api/agent-profiles")) return method === "GET" ? "agent:read" : "agent:write";