agent-relay-server 0.92.0 → 0.93.0

package/src/notification-router.ts

@@ -1,7 +1,11 @@
 import { notifySystemMessage } from "./notify";
-import type { Message, MessageKind } from "./types";
+import { createActivityEvent, getAgent, getMessage } from "./db";
+import { subscriptionDecisionFor } from "./db/notification-subscriptions";
+import { notificationEnabledFor } from "./notification-settings-store";
+import type { Message, MessageKind, NotificationRoutingExplanation, NotificationRoutingPreview, NotificationRoutingRecipientInput } from "./types";
 import { DEFAULT_TTL_MS } from "./notification-types";
 import type { NotificationScope, NotificationType } from "./notification-types";
+import { resolveAudience } from "./notification-rules";
 
 export {
   DEFAULT_TTL_MS,
@@ -44,7 +48,7 @@ interface RouteNotificationInput {
    * durable targets (`policy:`, `team:`, `label:`, `broadcast`, …) — the delivery layer resolves
    * durable forms at poll time. #442 will derive this set from `scope` via the rule engine.
    */
-  recipients: Array<string | undefined | null>;
+  recipients?: Array<string | NotificationRoutingRecipientInput | undefined | null>;
   message: NotificationMessage;
   /**
    * #451 — time-to-live in ms from `emittedAt`, after which the notification is stale and must not
@@ -82,8 +86,8 @@ export function routeNotification(input: RouteNotificationInput): Message[] {
   // router correct for any caller that routes a delayed/replayed event.
   if (ttl !== null && Date.now() - emittedAt > ttl) return [];
 
-  const recipients = [...new Set(input.recipients.filter((r): r is string => Boolean(r && r.trim())))];
-  if (recipients.length === 0) return [];
+  const preview = previewNotificationRouting(input);
+  if (preview.recipients.length === 0) return [];
 
   // Stamp the TTL on the message so the delivery/poll path (pollMessages) enforces it for offline
   // or late-joining recipients too. An explicit `null` (never-expire) is authoritative: it suppresses
@@ -91,16 +95,166 @@ export function routeNotification(input: RouteNotificationInput): Message[] {
   // never-expire intent instead of inheriting the moderate baseline.
   const maxAgeSeconds = ttl === null ? null : Math.max(1, Math.ceil(ttl / 1000));
 
-  return recipients.map((to) =>
-    notifySystemMessage(to, {
+  return preview.recipients.map((routing) => {
+    const message = notifySystemMessage(routing.recipient, {
       subject: input.message.subject,
       body: input.message.body,
-      payload: input.message.payload,
+      payload: { ...(input.message.payload ?? {}), routing: compactRoutingExplanation(routing) },
       idempotencyKey: input.message.idempotencyKey,
       kind: input.message.kind,
       from: input.message.from,
       replyExpected: input.message.replyExpected,
       maxAgeSeconds,
-    }),
-  );
+    });
+    auditRoutingTrace(message, preview, maxAgeSeconds);
+    return message;
+  });
+}
+
+export function previewNotificationRouting(input: Pick<RouteNotificationInput, "type" | "scope" | "recipients">): NotificationRoutingPreview {
+  const candidates = normalizeRoutingRecipients(input);
+  const recipients: NotificationRoutingExplanation[] = [];
+  const suppressed: NotificationRoutingExplanation[] = [];
+  for (const candidate of candidates) {
+    const settingsEnabled = notificationRecipientEnabled(input.type, candidate.agentId, input.scope);
+    const subscriptionState = subscriptionStateFor(input.type, candidate.agentId, input.scope);
+    const matchedRule = candidate.matchedRule || inferMatchedRule(candidate.agentId, input.scope);
+    const explanation: NotificationRoutingExplanation = {
+      type: input.type,
+      recipient: candidate.agentId,
+      matchedRule,
+      reason: candidate.reason || routingReason(matchedRule, candidate.agentId, input.scope, subscriptionState, settingsEnabled),
+      scope: input.scope as Record<string, unknown>,
+      subscriptionState,
+      settingsEnabled,
+    };
+    if (settingsEnabled) recipients.push(explanation);
+    else suppressed.push({ ...explanation, matchedRule: "settings:notifications" });
+  }
+  return { type: input.type, scope: input.scope as Record<string, unknown>, recipients, suppressed };
+}
+
+export function whyNotified(messageId: number, agentId: string): (NotificationRoutingExplanation & { messageId: number; agentId: string }) | null {
+  const message = getMessage(messageId);
+  if (!message) return null;
+  const routing = routingExplanationFromPayload(message.payload?.routing);
+  if (!routing) return null;
+  if (routing.recipient !== agentId && message.to !== agentId && message.resolvedToAgent !== agentId) return null;
+  return { ...routing, messageId, agentId };
+}
+
+function notificationRecipientEnabled(type: NotificationType, recipient: string, scope: NotificationScope): boolean {
+  const agent = getAgent(recipient);
+  return notificationEnabledFor(type, {
+    agentId: agent?.id ?? recipient,
+    teamId: agent?.teamId ?? scope.teamId,
+  });
+}
+
+function normalizeRoutingRecipients(input: Pick<RouteNotificationInput, "type" | "scope" | "recipients">): NotificationRoutingRecipientInput[] {
+  const raw = input.recipients === undefined
+    ? resolveAudience(input.type, input.scope).map((member) => ({ agentId: member.agentId, matchedRule: member.matchedRule }))
+    : input.recipients;
+  const byAgent = new Map<string, NotificationRoutingRecipientInput>();
+  for (const item of raw) {
+    const candidate = normalizeRoutingRecipient(item);
+    if (!candidate || byAgent.has(candidate.agentId)) continue;
+    byAgent.set(candidate.agentId, candidate);
+  }
+  return [...byAgent.values()];
+}
+
+function normalizeRoutingRecipient(value: string | NotificationRoutingRecipientInput | null | undefined): NotificationRoutingRecipientInput | null {
+  if (typeof value === "string") {
+    const agentId = value.trim();
+    return agentId ? { agentId } : null;
+  }
+  if (!value) return null;
+  const agentId = typeof value.agentId === "string" ? value.agentId.trim() : "";
+  if (!agentId) return null;
+  return {
+    agentId,
+    matchedRule: typeof value.matchedRule === "string" && value.matchedRule.trim() ? value.matchedRule.trim() : undefined,
+    reason: typeof value.reason === "string" && value.reason.trim() ? value.reason.trim() : undefined,
+  };
+}
+
+function inferMatchedRule(recipient: string, scope: NotificationScope): string {
+  if (scope.author && recipient === scope.author) return "author";
+  if (scope.parent && recipient === scope.parent) return "spawn-parent";
+  if (scope.agentId && recipient === scope.agentId) return "subject-agent";
+  const agent = getAgent(recipient);
+  if (scope.teamId && agent?.teamId === scope.teamId) return "same-team";
+  return "explicit-recipient";
+}
+
+function subscriptionStateFor(type: NotificationType, recipient: string, scope: NotificationScope): NotificationRoutingExplanation["subscriptionState"] {
+  const agent = getAgent(recipient);
+  if (!agent) return "unknown";
+  return subscriptionDecisionFor(agent, { type, scope, now: Date.now() });
+}
+
+function routingReason(
+  matchedRule: string,
+  recipient: string,
+  scope: NotificationScope,
+  subscriptionState: NotificationRoutingExplanation["subscriptionState"],
+  settingsEnabled: boolean,
+): string {
+  if (!settingsEnabled) return "notifications are disabled for this recipient by settings";
+  if (matchedRule === "author") return "you are the author";
+  if (matchedRule === "spawn-parent") return "you are the spawn parent";
+  if (matchedRule === "subject-agent") return "you are the notification subject";
+  if (matchedRule === "same-team") return scope.teamId ? `same team ${scope.teamId}` : "same team";
+  if (matchedRule === "on-repo-root") return scope.repoRoot ? `online in repo root ${scope.repoRoot}` : "online in the repo root";
+  if (matchedRule === "subscription:store" || subscriptionState === "deliver") return "explicit subscription matched";
+  if (matchedRule === "settings:notifications") return "notifications are disabled for this recipient by settings";
+  return `explicit recipient ${recipient}`;
+}
+
+function compactRoutingExplanation(routing: NotificationRoutingExplanation): NotificationRoutingExplanation {
+  return routing;
+}
+
+function routingExplanationFromPayload(value: unknown): NotificationRoutingExplanation | null {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return null;
+  const record = value as Record<string, unknown>;
+  if (typeof record.type !== "string" || typeof record.recipient !== "string" || typeof record.matchedRule !== "string") return null;
+  return {
+    type: record.type as NotificationType,
+    recipient: record.recipient,
+    matchedRule: record.matchedRule,
+    reason: typeof record.reason === "string" ? record.reason : "",
+    scope: record.scope && typeof record.scope === "object" && !Array.isArray(record.scope) ? record.scope as Record<string, unknown> : {},
+    subscriptionState: record.subscriptionState === "deliver" || record.subscriptionState === "suppress" || record.subscriptionState === "abstain"
+      ? record.subscriptionState
+      : "unknown",
+    settingsEnabled: record.settingsEnabled !== false,
+  };
+}
+
+function auditRoutingTrace(message: Message, preview: NotificationRoutingPreview, maxAgeSeconds: number | null): void {
+  try {
+    createActivityEvent({
+      kind: "state",
+      title: "Notification routed",
+      body: preview.recipients.find((item) => item.recipient === message.to)?.reason,
+      icon: "ti-route",
+      view: "messages",
+      messageId: message.id,
+      agentId: message.to,
+      metadata: {
+        source: "notification-router",
+        notificationType: preview.type,
+        scope: preview.scope as Record<string, unknown>,
+        routing: {
+          delivered: preview.recipients,
+          suppressed: preview.suppressed,
+          maxAgeSeconds,
+        },
+      },
+    });
+  } catch {
+    // Routing audit must never block notification delivery.
+  }
 }

package/src/notification-rules.ts

@@ -1,6 +1,7 @@
 import type { AgentCard } from "./types";
 import { listAgents } from "./db";
 import { isAgentOnline } from "./agent-ref";
+import { notificationEnabledFor } from "./notification-settings-store";
 import type { NotificationType, NotificationScope } from "./notification-types";
 
 /**
@@ -154,6 +155,11 @@ export function registerDefaultAudienceRules(type: NotificationType, rules: Noti
 // #443 subscription seam: opt-in / opt-out / mute become override rules injected here. They run AFTER
 // a type's default rules so they win the last-wins fold. Empty until #443 wires a subscription store.
 let subscriptionRules: NotificationRule[] = [];
+const settingsRule: NotificationRule = {
+  name: "settings:notifications",
+  evaluate: (agent, { type, scope }) =>
+    notificationEnabledFor(type, { agentId: agent.id, teamId: agent.teamId ?? scope.teamId }) ? "abstain" : "suppress",
+};
 
 /** #443 hook: install the subscription override rules (opt-in/opt-out/mute). Pass [] to clear. */
 export function setSubscriptionRules(rules: NotificationRule[]): void {
@@ -164,7 +170,7 @@ export function setSubscriptionRules(rules: NotificationRule[]): void {
 function audienceRulesFor(type: NotificationType): NotificationRule[] {
   const defaults = audienceRegistry.get(type);
   if (!defaults) return [];
-  return subscriptionRules.length === 0 ? defaults : [...defaults, ...subscriptionRules];
+  return [...defaults, ...subscriptionRules, settingsRule];
 }
 
 /**

package/src/notification-settings-store.ts

@@ -0,0 +1,47 @@
+import { getConfig, getNotificationsConfig, listConfig } from "./config-store";
+import {
+  NOTIFICATIONS_DEFAULT_KEY,
+  NOTIFICATIONS_NAMESPACE,
+  mergeNotificationSettings,
+  notificationAgentKey,
+  notificationTeamKey,
+  notificationTypeEnabled,
+  parseNotificationSettingsKey,
+  validateNotificationSettingsLayer,
+  type NotificationSettingsTarget,
+  type NotificationSettingLayer,
+} from "./notification-settings";
+import { registerNotificationSettingDescriptor } from "./settings/registry";
+import type { NotificationsConfig } from "./types";
+import type { NotificationType } from "./notification-types";
+
+export function ensureNotificationSettingDescriptors(extraKeys: string[] = []): void {
+  const keys = new Set<string>([NOTIFICATIONS_DEFAULT_KEY]);
+  for (const entry of listConfig(NOTIFICATIONS_NAMESPACE)) keys.add(entry.key);
+  for (const key of extraKeys) keys.add(key);
+
+  for (const key of keys) {
+    if (!parseNotificationSettingsKey(key)) continue;
+    registerNotificationSettingDescriptor(key);
+  }
+}
+
+export function getResolvedNotificationsConfig(target: NotificationSettingsTarget = {}): NotificationsConfig {
+  let config = getNotificationsConfig();
+  if (target.teamId) {
+    config = mergeNotificationSettings(config, notificationSettingsLayer(notificationTeamKey(target.teamId)));
+  }
+  if (target.agentId) {
+    config = mergeNotificationSettings(config, notificationSettingsLayer(notificationAgentKey(target.agentId)));
+  }
+  return config;
+}
+
+export function notificationEnabledFor(type: NotificationType, target: NotificationSettingsTarget = {}): boolean {
+  return notificationTypeEnabled(getResolvedNotificationsConfig(target), type);
+}
+
+function notificationSettingsLayer(key: string): NotificationSettingLayer | null {
+  const entry = getConfig<NotificationSettingLayer>(NOTIFICATIONS_NAMESPACE, key);
+  return entry ? validateNotificationSettingsLayer(entry.value) : null;
+}

package/src/notification-settings.ts

@@ -0,0 +1,155 @@
+import { isRecord } from "agent-relay-sdk";
+import type { JSONSchema } from "agent-relay-sdk";
+import { ValidationError } from "./db/connection.ts";
+import { DEFAULT_CONTEXT_THRESHOLD_CONFIG, validateContextThresholdConfig } from "./context-threshold-config";
+import { DEFAULT_QUOTA_THRESHOLD_CONFIG, validateQuotaThresholdConfig } from "./quota-threshold-config";
+import type { NotificationsConfig } from "./types";
+import type { NotificationType } from "./notification-types";
+
+export const NOTIFICATIONS_NAMESPACE = "notifications";
+export const NOTIFICATIONS_DEFAULT_KEY = "default";
+const TEAM_KEY_PREFIX = "team:";
+const AGENT_KEY_PREFIX = "agent:";
+
+type NotificationToggleKey = "branchLanded" | "agentReady" | "agentExited" | "agentSpawnFailed";
+export type NotificationSettingLayer = Partial<NotificationsConfig>;
+
+export interface NotificationSettingsTarget {
+  agentId?: string;
+  teamId?: string;
+}
+
+export const NOTIFICATIONS_CONFIG_DEFAULTS: NotificationsConfig = {
+  enabled: true,
+  branchLanded: true,
+  agentReady: true,
+  agentExited: true,
+  agentSpawnFailed: true,
+  contextThreshold: DEFAULT_CONTEXT_THRESHOLD_CONFIG,
+  quotaThreshold: DEFAULT_QUOTA_THRESHOLD_CONFIG,
+};
+
+export const CONTEXT_THRESHOLD_SETTINGS_SCHEMA: JSONSchema = {
+  type: "object",
+  additionalProperties: false,
+  properties: {
+    enabled: { type: "boolean" },
+    advisoryUtilization: { type: "number", minimum: 0, maximum: 1 },
+    selfCompactUtilization: { type: "number", minimum: 0, maximum: 1 },
+    warnUtilization: { type: "number", minimum: 0, maximum: 1 },
+    hardBackstopUtilization: { type: "number", minimum: 0, maximum: 1 },
+    bandSize: { type: "number", exclusiveMinimum: 0, maximum: 1 },
+  },
+};
+
+export const QUOTA_THRESHOLD_SETTINGS_SCHEMA: JSONSchema = {
+  type: "object",
+  additionalProperties: false,
+  properties: {
+    enabled: { type: "boolean" },
+    warnRemaining: { type: "number", minimum: 0, maximum: 1 },
+    criticalRemaining: { type: "number", minimum: 0, maximum: 1 },
+    resetRemaining: { type: "number", minimum: 0, maximum: 1 },
+    bandSize: { type: "number", exclusiveMinimum: 0, maximum: 1 },
+  },
+};
+
+export const NOTIFICATIONS_SETTINGS_SCHEMA: JSONSchema = {
+  type: "object",
+  additionalProperties: false,
+  properties: {
+    enabled: { type: "boolean" },
+    branchLanded: { type: "boolean" },
+    agentReady: { type: "boolean" },
+    agentExited: { type: "boolean" },
+    agentSpawnFailed: { type: "boolean" },
+    contextThreshold: CONTEXT_THRESHOLD_SETTINGS_SCHEMA,
+    quotaThreshold: QUOTA_THRESHOLD_SETTINGS_SCHEMA,
+  },
+};
+
+export function notificationTeamKey(teamId: string): string {
+  return `${TEAM_KEY_PREFIX}${cleanLayerId(teamId, "teamId")}`;
+}
+
+export function notificationAgentKey(agentId: string): string {
+  return `${AGENT_KEY_PREFIX}${cleanLayerId(agentId, "agentId")}`;
+}
+
+export function parseNotificationSettingsKey(key: string): { kind: "default" | "team" | "agent"; id?: string } | null {
+  if (key === NOTIFICATIONS_DEFAULT_KEY) return { kind: "default" };
+  if (key.startsWith(TEAM_KEY_PREFIX)) {
+    const id = key.slice(TEAM_KEY_PREFIX.length).trim();
+    return id ? { kind: "team", id } : null;
+  }
+  if (key.startsWith(AGENT_KEY_PREFIX)) {
+    const id = key.slice(AGENT_KEY_PREFIX.length).trim();
+    return id ? { kind: "agent", id } : null;
+  }
+  return null;
+}
+
+export function validateNotificationsConfig(value: unknown): NotificationsConfig {
+  return mergeNotificationSettings(NOTIFICATIONS_CONFIG_DEFAULTS, validateNotificationSettingsLayer(value));
+}
+
+export function validateNotificationSettingsLayer(value: unknown): NotificationSettingLayer {
+  if (!isRecord(value)) throw new ValidationError("notifications config value must be an object");
+  const bool = (key: "enabled" | NotificationToggleKey): boolean | undefined =>
+    value[key] === undefined ? undefined : cleanBoolean(value[key], key);
+  return {
+    ...(bool("enabled") !== undefined ? { enabled: bool("enabled")! } : {}),
+    ...(bool("branchLanded") !== undefined ? { branchLanded: bool("branchLanded")! } : {}),
+    ...(bool("agentReady") !== undefined ? { agentReady: bool("agentReady")! } : {}),
+    ...(bool("agentExited") !== undefined ? { agentExited: bool("agentExited")! } : {}),
+    ...(bool("agentSpawnFailed") !== undefined ? { agentSpawnFailed: bool("agentSpawnFailed")! } : {}),
+    ...(value.contextThreshold === undefined ? {} : { contextThreshold: validateContextThresholdConfig(value.contextThreshold) }),
+    ...(value.quotaThreshold === undefined ? {} : { quotaThreshold: validateQuotaThresholdConfig(value.quotaThreshold) }),
+  };
+}
+
+export function mergeNotificationSettings(base: NotificationsConfig, layer: NotificationSettingLayer | null | undefined): NotificationsConfig {
+  if (!layer) return base;
+  return {
+    ...base,
+    ...withoutNestedThresholds(layer),
+    contextThreshold: layer.contextThreshold ? { ...base.contextThreshold, ...layer.contextThreshold } : base.contextThreshold,
+    quotaThreshold: layer.quotaThreshold ? { ...base.quotaThreshold, ...layer.quotaThreshold } : base.quotaThreshold,
+  };
+}
+
+export function notificationTypeEnabled(config: NotificationsConfig, type: NotificationType): boolean {
+  if (!config.enabled) return false;
+  if (type === "agent.context_threshold") return config.contextThreshold.enabled;
+  if (type === "agent.quota_threshold") return config.quotaThreshold.enabled;
+  const key = notificationToggleForType(type);
+  return key ? config[key] : true;
+}
+
+function notificationToggleForType(type: NotificationType): NotificationToggleKey | null {
+  if (type === "branch.landed" || type === "landed-failure") return "branchLanded";
+  if (type === "agent.ready") return "agentReady";
+  if (type === "agent.exited") return "agentExited";
+  if (type === "agent.spawn_failed") return "agentSpawnFailed";
+  return null;
+}
+
+function withoutNestedThresholds(layer: NotificationSettingLayer): Omit<NotificationSettingLayer, "contextThreshold" | "quotaThreshold"> {
+  const { contextThreshold: _contextThreshold, quotaThreshold: _quotaThreshold, ...rest } = layer;
+  return rest;
+}
+
+function cleanBoolean(value: unknown, field: string): boolean {
+  if (typeof value !== "boolean") throw new ValidationError(`${field} must be a boolean`);
+  return value;
+}
+
+function cleanLayerId(value: string, field: string): string {
+  const clean = value.trim();
+  if (!clean) throw new ValidationError(`${field} required`);
+  if (clean.length > 200) throw new ValidationError(`${field} must be at most 200 characters`);
+  if (clean.includes("/") || clean.includes("\n") || clean.includes("\r")) {
+    throw new ValidationError(`${field} must not contain slashes or newlines`);
+  }
+  return clean;
+}

package/src/notification-types.ts

@@ -84,5 +84,7 @@ export const DEFAULT_TTL_MS: Record<NotificationType, number | null> = {
   "workspace.review_changes_requested": null,
 };
 
+export const NOTIFICATION_TYPES = Object.keys(DEFAULT_TTL_MS) as NotificationType[];
+
 /** Convenience TTL for emitter-supplied overrides on bystander/informational notifications. */
 export const INFORMATIONAL_TTL_MS = 30 * MINUTES;

package/src/quota-advisory.ts

@@ -165,9 +165,6 @@ function notifyQuotaAdvisory(input: {
     data: payload,
   });
 
-  const notifications = effectiveQuotaNotificationConfig();
-  if (!notifications.enabled || !notifications.quotaThreshold.enabled) return;
-
   routeNotification({
     type: "agent.quota_threshold",
     scope: {},

package/src/routes/index.ts

@@ -40,6 +40,7 @@ import { deleteIssueRefRoute, getIssueRefRoute, listIssueRefsRoute, patchIssueRe
 import { getProjectEntriesRoute, getProjectEntryRoute, getProjectResolveRoute, getProjectRoute, getProjectsRoute } from "./projects";
 import { getRecipeByName, getRecipeInstanceArtifacts, getRecipeInstanceById, getRecipeInstances, getRecipes, postRecipeInstanceArtifacts, postRecipeStart, postRecipeStop } from "./recipes";
 import { getSettingRoute, getSettingsNamespaceRoute, getSettingsRoute, putSettingRoute, putSettingsDefaultRoute } from "./settings";
+import { postNotificationPreviewRoute } from "./notifications";
 import { getStewardConfigRoute, getWorkspaceConfigRoute, putStewardConfigRoute, putWorkspaceConfigRoute } from "./steward";
 import { getTaskById, getTaskEvents, getTasks, patchTaskStatus, postClaimTask, postRenewTaskClaim } from "./tasks";
 import { getMyTeamRoute, getTeamOutcomesRoute, getTeamsRoute, postMyTeamDissolveRoute, putMyTeamBriefRoute } from "./teams";
@@ -246,6 +247,7 @@ const routes: Route[] = [
   route("GET", "/api/settings/:namespace/:key", getSettingRoute),
   route("PUT", "/api/settings/:namespace", putSettingsDefaultRoute),
   route("PUT", "/api/settings/:namespace/:key", putSettingRoute),
+  route("POST", "/api/notifications/preview", postNotificationPreviewRoute),
   route("GET", "/api/config/:namespace", getConfigNamespace),
   route("GET", "/api/config/:namespace/:key/history", getConfigKeyHistory),
   route("GET", "/api/config/:namespace/:key", getConfigKey),

package/src/routes/notifications.ts

@@ -0,0 +1,36 @@
+// Domain: notification routing preview/explainability (#446).
+import { isRecord } from "agent-relay-sdk";
+import { ValidationError } from "../db";
+import { NOTIFICATION_TYPES, type NotificationScope, type NotificationType } from "../notification-types";
+import { previewNotificationRouting } from "../notification-router";
+import { error, json, parseBody, type Handler } from "./_shared";
+
+export const postNotificationPreviewRoute: Handler = async (req) => {
+  const parsed = await parseBody<unknown>(req);
+  if (!parsed.ok) return error(parsed.error, parsed.status);
+  try {
+    if (!isRecord(parsed.body)) return error("JSON object body required");
+    return json({
+      preview: previewNotificationRouting({
+        type: cleanNotificationType(parsed.body.type),
+        scope: cleanScope(parsed.body.scope),
+      }),
+    });
+  } catch (e) {
+    if (e instanceof ValidationError) return error(e.message, 400);
+    throw e;
+  }
+};
+
+function cleanNotificationType(value: unknown): NotificationType {
+  if (typeof value !== "string" || !NOTIFICATION_TYPES.includes(value as NotificationType)) {
+    throw new ValidationError(`type must be one of: ${NOTIFICATION_TYPES.join(", ")}`);
+  }
+  return value as NotificationType;
+}
+
+function cleanScope(value: unknown): NotificationScope {
+  if (value === undefined || value === null) return {};
+  if (!isRecord(value)) throw new ValidationError("scope must be an object");
+  return value as NotificationScope;
+}

package/src/routes/settings.ts

@@ -3,6 +3,8 @@ import { ValidationError } from "../db";
 import { getConfig, setConfig } from "../config-store";
 import { getUserSetting, setUserSetting } from "../user-settings-store";
 import { ensureProviderConfigDescriptors, migrateLocalProviderConfigs } from "../provider-config-store";
+import { ensureNotificationSettingDescriptors } from "../notification-settings-store";
+import { NOTIFICATIONS_NAMESPACE } from "../notification-settings";
 import { getSettingDescriptor, listSettingDescriptors, validateSettingValue, PROVIDER_CONFIG_NAMESPACE } from "../settings/registry";
 import { isRequestAuthorizedFor } from "../security";
 import { cleanString } from "../validation";
@@ -21,6 +23,7 @@ type SettingEnvelope = SettingEntry;
 export const getSettingsRoute: Handler = (req) => {
   migrateLocalProviderConfigs();
   ensureProviderConfigDescriptors();
+  ensureNotificationSettingDescriptors();
   return json({ settings: listVisibleSettings(req) });
 };
 
@@ -28,6 +31,7 @@ export const getSettingsNamespaceRoute: Handler = (req, params) => {
   const namespace = normalizeConfigPathParam(params.namespace, "namespace");
   migrateLocalProviderConfigs();
   ensureProviderConfigDescriptors();
+  if (namespace === NOTIFICATIONS_NAMESPACE) ensureNotificationSettingDescriptors();
   return json({ settings: listVisibleSettings(req).filter((setting) => setting.namespace === namespace) });
 };
 
@@ -36,6 +40,7 @@ export const getSettingRoute: Handler = (req, params) => {
   const key = normalizeConfigPathParam(params.key, "key");
   migrateLocalProviderConfigs();
   ensureProviderConfigDescriptors(namespace === PROVIDER_CONFIG_NAMESPACE ? [key] : []);
+  if (namespace === NOTIFICATIONS_NAMESPACE) ensureNotificationSettingDescriptors([key]);
   const descriptor = getSettingDescriptor(namespace, key);
   if (!descriptor) return error("setting not found", 404);
   const readable = canAccessSetting(req, descriptor.scope.read);
@@ -76,6 +81,7 @@ async function putSetting(req: Request, namespaceRaw: string | undefined, keyRaw
   try {
     migrateLocalProviderConfigs();
     ensureProviderConfigDescriptors(namespace === PROVIDER_CONFIG_NAMESPACE ? [key] : []);
+    if (namespace === NOTIFICATIONS_NAMESPACE) ensureNotificationSettingDescriptors([key]);
     const descriptor = getSettingDescriptor(namespace, key);
     if (!descriptor) return error("setting not found", 404);
     if (descriptor.tier !== "server-runtime" && descriptor.tier !== "user") return error("setting is read-only", 403);

package/src/security.ts

@@ -151,6 +151,7 @@ export function requiredScopeFor(method: string, pathname: string): string | nul
   if (pathname === "/api/health") return "health:read";
   if (pathname === "/api/events") return "events:read";
   if (pathname === "/api/route") return "agent:read";
+  if (pathname === "/api/notifications/preview") return "notifications:read";
   if (pathname === "/api/mcp") return "mcp:use";
   if (pathname === "/api/orchestrators/bootstrap/exchange") return "token:write";
   if (pathname === "/api/orchestrators/bootstrap") return "token:write";

package/src/services/scheduler.ts

@@ -39,9 +39,13 @@ export interface ScheduleTimerInput {
   everyMs?: number;
   rrule?: string;
   timezone?: string;
+  kind?: SendMessageInput["kind"];
+  channel?: string;
   subject?: string;
   body: string;
+  claimable?: boolean;
   payload?: Record<string, unknown>;
+  meta?: Record<string, unknown>;
   maxRuns?: number;
   expiresAt?: string | number;
   idempotencyKey?: string;
@@ -78,9 +82,13 @@ export function scheduleTimer(input: ScheduleTimerInput, ctx: AuthContext): Sche
   const deliveryFrom = ctx.callerAgentId ?? "system";
   const body = cleanBody(input.body);
   const payload = cleanPayload(input.payload);
+  const meta = cleanPayload(input.meta);
   const maxRuns = cleanPositiveInt(input.maxRuns, "maxRuns");
   const expiresAt = cleanExpiresAt(input.expiresAt, now);
   const idempotencyKey = cleanOptionalString(input.idempotencyKey, "idempotencyKey", 240);
+  const messageKind = cleanOptionalString(input.kind, "kind", 40) as SendMessageInput["kind"] | undefined;
+  const channel = cleanOptionalString(input.channel, "channel", 120);
+  const claimable = cleanOptionalBoolean(input.claimable, "claimable");
 
   if (schedule.kind === "interval") {
     if ((schedule.def.everyMs ?? 0) < SCHEDULER_MIN_RECURRING_INTERVAL_MS) {
@@ -100,9 +108,13 @@ export function scheduleTimer(input: ScheduleTimerInput, ctx: AuthContext): Sche
   validateSendMessageAuthorization({
     from: deliveryFrom,
     to: target,
+    kind: messageKind,
+    channel,
     body,
     subject: cleanOptionalString(input.subject, "subject", 200),
+    claimable,
     payload,
+    meta,
     idempotencyKey: idempotencyKey ? `${idempotencyKey}:probe` : undefined,
   }, ctx);
 
@@ -116,9 +128,13 @@ export function scheduleTimer(input: ScheduleTimerInput, ctx: AuthContext): Sche
     nextRunAt: schedule.nextRunAt,
     scheduleKind: schedule.kind,
     scheduleDef: schedule.def,
+    messageKind,
+    channel,
     subject: cleanOptionalString(input.subject, "subject", 200),
     body,
+    claimable,
     payload,
+    meta,
     maxRuns,
     expiresAt,
     idempotencyKey,
@@ -176,8 +192,11 @@ function fireClaimedTimer(timer: ScheduledTimer, now: number): { status: "fired"
     const result = sendMessageService({
       from: timer.deliveryFrom,
       to: timer.target,
+      kind: timer.messageKind as SendMessageInput["kind"] | undefined,
+      channel: timer.channel,
       subject: timer.subject,
       body: timer.body,
+      claimable: timer.claimable,
       payload: {
         ...timer.payload,
         scheduler: {
@@ -187,6 +206,7 @@ function fireClaimedTimer(timer: ScheduledTimer, now: number): { status: "fired"
         },
       },
       meta: {
+        ...timer.meta,
         scheduler: {
           timerId: timer.id,
           correlationId: timer.correlationId,
@@ -199,7 +219,7 @@ function fireClaimedTimer(timer: ScheduledTimer, now: number): { status: "fired"
     return { status: "fired", messageId: result.message.id };
   } catch (error) {
     const updated = recordScheduledTimerFailure({
-      id: timer.id,
+      timer,
       error: errMessage(error),
       now,
       retryMs: SCHEDULER_RETRY_MS,
@@ -215,6 +235,8 @@ function timerRunIdempotencyKey(timer: ScheduledTimer, runNumber: number): strin
 }
 
 function persistedAuthContext(timer: ScheduledTimer): AuthContext {
+  // Timers intentionally fire with the create-time component scope snapshot. That keeps durable
+  // sends restart-safe; a stricter future model can revalidate a live token at fire time.
   const component: ComponentToken = {
     sub: timer.createdBy,
     role: timer.createdByKind,
@@ -287,6 +309,12 @@ function cleanPositiveInt(value: unknown, field: string): number | undefined {
   return value;
 }
 
+function cleanOptionalBoolean(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;
+}
+
 function cleanExpiresAt(value: unknown, now: number): number | undefined {
   if (value === undefined || value === null) return undefined;
   const ms = typeof value === "number" ? value : typeof value === "string" ? Date.parse(value) : NaN;