agent-relay-server 0.92.0 → 0.93.0

package/src/branch-landed.ts

@@ -1,8 +1,7 @@
 import { errMessage } from "agent-relay-sdk";
 import { emitRelayEvent } from "./events";
-import { getNotificationsConfig } from "./config-store";
 import { routeNotification, INFORMATIONAL_TTL_MS } from "./notification-router";
-import { registerDefaultAudienceRules, resolveAudience, audiencePredicates } from "./notification-rules";
+import { registerDefaultAudienceRules, audiencePredicates } from "./notification-rules";
 import { createActivityEvent, getAgent, updateWorkspaceStatus } from "./db";
 import { handleLandedIssueLifecycle } from "./services/issue-lifecycle";
 import type { WorkspaceMergePreview, WorkspaceRecord } from "./types";
@@ -135,9 +134,6 @@ export function notifyBranchLanded(input: BranchLandedInput): void {
     console.warn(`issue lifecycle land hook failed for ${workspace.id}: ${errMessage(error)}`);
   });
 
-  const config = getNotificationsConfig();
-  if (!config.enabled || !config.branchLanded) return;
-
   const author = workspace.ownerAgentId;
   const shaLabel = shortSha ? ` as \`${shortSha}\`` : "";
   const subjectLabel = input.subject ? ` — "${input.subject}"` : "";
@@ -186,25 +182,22 @@ export function notifyBranchLanded(input: BranchLandedInput): void {
   // online agents whose cwd is the main checkout, author-excluded, team-scoped. Empty for a solo
   // land with no other main agents → no-op.
   const mainScope = { author, repoRoot: workspace.repoRoot, workspaceId: workspace.id, teamId: author ? getAgent(author)?.teamId : undefined };
-  const mainRecipients = resolveAudience("branch.landed", mainScope).map((member) => member.agentId);
-  if (mainRecipients.length > 0) {
-    const branchLabel = landedBranch ? `\`${landedBranch}\`` : "A branch";
-    const authorLabel = author ? ` by \`${author}\`` : "";
-    // Bystander fan-out (ttl informational): a "merged" notice is only useful while fresh — a
-    // late-joining main agent shouldn't be woken by an hours-old land.
-    routeNotification({
-      type: "branch.landed",
-      scope: mainScope,
-      recipients: mainRecipients,
-      ttlMs: INFORMATIONAL_TTL_MS,
-      message: {
-        subject: `Merged to ${base}`,
-        body: `🔀 ${branchLabel}${authorLabel} merged to \`${base}\`${shaLabel}${subjectLabel}.${publishLabel}`,
-        payload: { ...payload, notification: "landed-success" },
-        replyExpected: false,
-      },
-    });
-  }
+  const branchLabel = landedBranch ? `\`${landedBranch}\`` : "A branch";
+  const authorLabel = author ? ` by \`${author}\`` : "";
+  // Bystander fan-out (ttl informational): a "merged" notice is only useful while fresh — a
+  // late-joining main agent shouldn't be woken by an hours-old land. Omit explicit recipients so
+  // the notification router records the full #442 rule decision for #446's routed-because trace.
+  routeNotification({
+    type: "branch.landed",
+    scope: mainScope,
+    ttlMs: INFORMATIONAL_TTL_MS,
+    message: {
+      subject: `Merged to ${base}`,
+      body: `🔀 ${branchLabel}${authorLabel} merged to \`${base}\`${shaLabel}${subjectLabel}.${publishLabel}`,
+      payload: { ...payload, notification: "landed-success" },
+      replyExpected: false,
+    },
+  });
 }
 
 /**
@@ -240,8 +233,6 @@ export function notifyBranchLandFailed(input: {
   });
 
   if (!author) return;
-  const config = getNotificationsConfig();
-  if (!config.enabled || !config.branchLanded) return;
   const branchLabel = workspace.branch ? `\`${workspace.branch}\`` : "Your branch";
   routeNotification({
     type: "landed-failure",
@@ -298,9 +289,6 @@ export function notifyStewardHandoff(input: {
 
   emitRelayEvent({ type: "workspace.steward_handoff", source: "server", subject: workspace.id, data: payload });
 
-  const config = getNotificationsConfig();
-  if (!config.enabled) return;
-
   // #641 — tell the owner branch agent which steward now holds its merge, so it stops
   // thinking the branch silently failed. Durable (ttl null): the owner must learn this
   // even if it went idle. Mirror the "don't touch main" guardrail of the landed-failure wake.

package/src/config-store.ts

@@ -1,7 +1,13 @@
 import { getDb, ValidationError } from "./db";
 import { cleanEnum, cleanString, cleanStringArray } from "./validation";
-import { DEFAULT_CONTEXT_THRESHOLD_CONFIG, validateContextThresholdConfig } from "./context-threshold-config";
-import { DEFAULT_QUOTA_THRESHOLD_CONFIG, validateQuotaThresholdConfig } from "./quota-threshold-config";
+import {
+  NOTIFICATIONS_CONFIG_DEFAULTS,
+  NOTIFICATIONS_DEFAULT_KEY,
+  NOTIFICATIONS_NAMESPACE,
+  parseNotificationSettingsKey,
+  validateNotificationSettingsLayer,
+  validateNotificationsConfig,
+} from "./notification-settings";
 import { DEFAULT_SELF_RESUME_CONFIG, validateSelfResumeConfig } from "./self-resume-config";
 import { TEAM_TEMPLATE_NAMESPACE, validateTeamTemplate } from "./team-template-config";
 import { PROJECT_INSTRUCTION_POLICY_NAMES } from "./project-instructions";
@@ -36,8 +42,6 @@ const STEWARD_NAMESPACE = "steward";
 const STEWARD_KEY = "default";
 const INSIGHTS_NAMESPACE = "insights";
 const INSIGHTS_KEY = "default";
-const NOTIFICATIONS_NAMESPACE = "notifications";
-const NOTIFICATIONS_KEY = "default";
 const SELF_RESUME_NAMESPACE = "self-resume";
 const SELF_RESUME_KEY = "default";
 const WORKSPACE_NAMESPACE = "workspace";
@@ -549,26 +553,6 @@ function validateInsightsConfig(value: unknown): InsightsConfig {
   };
 }
 
-// Relay-driven lifecycle push notifications (#239 event bus). Default-on; the
-// operator can flip the master switch or individual events off via the generic
-// config route. Push messages wake recipients, so they must be suppressible.
-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 };
-
-function validateNotificationsConfig(value: unknown): NotificationsConfig {
-  if (!isRecord(value)) throw new ValidationError("notifications config value must be an object");
-  const bool = (key: "enabled" | "branchLanded" | "agentReady" | "agentExited" | "agentSpawnFailed"): boolean =>
-    value[key] === undefined ? NOTIFICATIONS_CONFIG_DEFAULTS[key] : cleanBoolean(value[key], key);
-  return {
-    enabled: bool("enabled"),
-    branchLanded: bool("branchLanded"),
-    agentReady: bool("agentReady"),
-    agentExited: bool("agentExited"),
-    agentSpawnFailed: bool("agentSpawnFailed"),
-    contextThreshold: validateContextThresholdConfig(value.contextThreshold),
-    quotaThreshold: validateQuotaThresholdConfig(value.quotaThreshold),
-  };
-}
-
 // Global workspace provisioning config for isolated worktrees (#159 follow-up).
 // Defaults seed the two untracked paths an isolated agent almost always needs:
 // the agent guide and the rig config, both gitignored so a fresh worktree lacks them.
@@ -609,7 +593,10 @@ function normalizeValue(namespace: string, key: string, value: unknown): unknown
   if (namespace === AGENT_PROFILE_NAMESPACE) return validateAgentProfile(key, value);
   if (namespace === STEWARD_NAMESPACE) return validateStewardConfig(value);
   if (namespace === INSIGHTS_NAMESPACE) return validateInsightsConfig(value);
-  if (namespace === NOTIFICATIONS_NAMESPACE) return validateNotificationsConfig(value);
+  if (namespace === NOTIFICATIONS_NAMESPACE) {
+    if (!parseNotificationSettingsKey(key)) throw new ValidationError("notifications config key must be default, team:<teamId>, or agent:<agentId>");
+    return key === NOTIFICATIONS_DEFAULT_KEY ? validateNotificationsConfig(value) : validateNotificationSettingsLayer(value);
+  }
   if (namespace === SELF_RESUME_NAMESPACE) return validateSelfResumeConfig(value);
   if (namespace === WORKSPACE_NAMESPACE) return validateWorkspaceConfig(value);
   if (namespace === LANDING_NAMESPACE) return validateLandingConfig(value);
@@ -748,7 +735,7 @@ export function getInsightsConfigEntry(): ConfigEntry<InsightsConfig> {
 
 /** Lifecycle-notification config (#239), merged over defaults (always usable). */
 export function getNotificationsConfig(): NotificationsConfig {
-  const entry = getConfig<Partial<NotificationsConfig>>(NOTIFICATIONS_NAMESPACE, NOTIFICATIONS_KEY);
+  const entry = getConfig<Partial<NotificationsConfig>>(NOTIFICATIONS_NAMESPACE, NOTIFICATIONS_DEFAULT_KEY);
   if (!entry) return { ...NOTIFICATIONS_CONFIG_DEFAULTS };
   return validateNotificationsConfig({ ...NOTIFICATIONS_CONFIG_DEFAULTS, ...entry.value });
 }

package/src/context-advisory.ts

@@ -1,7 +1,9 @@
 import { deriveContextThresholdFromWindowTokens, findProviderCatalogModel, resolveProviderContextThreshold, type ProviderModelCatalogEntry, type ResolvedProviderContextThreshold } from "agent-relay-sdk/provider-catalog";
 import { isRecord, SPAWN_PROVIDERS } from "agent-relay-sdk";
-import { getConfig, getNotificationsConfig } from "./config-store";
-import { DEFAULT_CONTEXT_THRESHOLD_CONFIG, validateContextThresholdConfig } from "./context-threshold-config";
+import { getConfig } from "./config-store";
+import { validateContextThresholdConfig } from "./context-threshold-config";
+import { getResolvedNotificationsConfig } from "./notification-settings-store";
+import { NOTIFICATIONS_DEFAULT_KEY, NOTIFICATIONS_NAMESPACE, notificationAgentKey, notificationTeamKey } from "./notification-settings";
 import { getDb } from "./db/connection.ts";
 import { emitRelayEvent } from "./events";
 import { routeNotification } from "./notification-router";
@@ -53,9 +55,6 @@ function notifyContextAdvisory(input: ContextAdvisoryInput): void {
     data: payload,
   });
 
-  const config = getNotificationsConfig();
-  if (!config.enabled || !config.contextThreshold.enabled) return;
-
   // Short default TTL (per-type): a stale context advisory is misleading — the band may have moved
   // by the time the agent next polls, so old advice shouldn't wake it.
   routeNotification({
@@ -140,15 +139,14 @@ function effectiveContextThreshold(agent: AgentCard): EffectiveContextThreshold
   if (model?.contextThreshold) {
     return { ...resolveProviderContextThreshold(model), source: "model" };
   }
-  const global = explicitContextThresholdConfig();
+  const global = explicitContextThresholdConfig(agent);
   if (global) return global;
   return { ...deriveContextThresholdFromWindowTokens(windowTokens), source: "window" };
 }
 
-function explicitContextThresholdConfig(): EffectiveContextThreshold | undefined {
-  const entry = getConfig("notifications", "default");
-  if (!entry || !isRecord(entry.value) || !isRecord(entry.value.contextThreshold)) return undefined;
-  const global = validateContextThresholdConfig({ ...DEFAULT_CONTEXT_THRESHOLD_CONFIG, ...entry.value.contextThreshold });
+function explicitContextThresholdConfig(agent: AgentCard): EffectiveContextThreshold | undefined {
+  if (!hasExplicitContextThreshold(agent)) return undefined;
+  const global = validateContextThresholdConfig(getResolvedNotificationsConfig({ agentId: agent.id, teamId: agent.teamId }).contextThreshold);
   const selfCompactUtilization = global.selfCompactUtilization ?? global.advisoryUtilization;
   return {
     selfCompactUtilization,
@@ -158,6 +156,18 @@ function explicitContextThresholdConfig(): EffectiveContextThreshold | undefined
   };
 }
 
+function hasExplicitContextThreshold(agent: AgentCard): boolean {
+  const keys = [
+    NOTIFICATIONS_DEFAULT_KEY,
+    ...(agent.teamId ? [notificationTeamKey(agent.teamId)] : []),
+    notificationAgentKey(agent.id),
+  ];
+  return keys.some((key) => {
+    const entry = getConfig(NOTIFICATIONS_NAMESPACE, key);
+    return isRecord(entry?.value) && isRecord(entry.value.contextThreshold);
+  });
+}
+
 function findAgentCatalogModel(agent: AgentCard, observedWindowTokens: number | undefined): ProviderModelCatalogEntry | undefined {
   const runtime = agent.providerCapabilities?.model;
   const provider = runtime?.provider;

package/src/db/migrations.ts

@@ -896,9 +896,13 @@ export function applyMigrations(): void {
       next_run_at INTEGER NOT NULL,
       schedule_kind TEXT NOT NULL,
       schedule_def TEXT NOT NULL,
+      message_kind TEXT,
+      channel TEXT,
       subject TEXT,
       body TEXT NOT NULL,
+      claimable INTEGER NOT NULL DEFAULT 0,
       payload TEXT NOT NULL DEFAULT '{}',
+      meta TEXT NOT NULL DEFAULT '{}',
       enabled INTEGER NOT NULL DEFAULT 1,
       run_count INTEGER NOT NULL DEFAULT 0,
       max_runs INTEGER,
@@ -913,6 +917,19 @@ export function applyMigrations(): void {
       claim_expires_at INTEGER
     )
   `);
+  const scheduledTimerCols = (getDb().query("PRAGMA table_info(scheduled_timers)").all() as any[]).map((c: any) => c.name);
+  if (!scheduledTimerCols.includes("message_kind")) {
+    getDb().run("ALTER TABLE scheduled_timers ADD COLUMN message_kind TEXT");
+  }
+  if (!scheduledTimerCols.includes("channel")) {
+    getDb().run("ALTER TABLE scheduled_timers ADD COLUMN channel TEXT");
+  }
+  if (!scheduledTimerCols.includes("claimable")) {
+    getDb().run("ALTER TABLE scheduled_timers ADD COLUMN claimable INTEGER NOT NULL DEFAULT 0");
+  }
+  if (!scheduledTimerCols.includes("meta")) {
+    getDb().run("ALTER TABLE scheduled_timers ADD COLUMN meta TEXT NOT NULL DEFAULT '{}'");
+  }
   getDb().run("CREATE INDEX IF NOT EXISTS idx_scheduled_timers_due ON scheduled_timers(enabled, next_run_at, claim_expires_at)");
   getDb().run("CREATE INDEX IF NOT EXISTS idx_scheduled_timers_creator ON scheduled_timers(created_by, enabled, next_run_at)");
   getDb().run("CREATE INDEX IF NOT EXISTS idx_scheduled_timers_correlation ON scheduled_timers(correlation_id)");

package/src/db/scheduled-timers.ts

@@ -22,9 +22,13 @@ export interface ScheduledTimer {
   nextRunAt: number;
   scheduleKind: TimerScheduleKind;
   scheduleDef: TimerScheduleDef;
+  messageKind?: string;
+  channel?: string;
   subject?: string;
   body: string;
+  claimable?: boolean;
   payload: Record<string, unknown>;
+  meta: Record<string, unknown>;
   enabled: boolean;
   runCount: number;
   maxRuns?: number;
@@ -51,9 +55,13 @@ interface ScheduledTimerRow {
   next_run_at: number;
   schedule_kind: string;
   schedule_def: string;
+  message_kind: string | null;
+  channel: string | null;
   subject: string | null;
   body: string;
+  claimable: number | null;
   payload: string;
+  meta: string | null;
   enabled: number;
   run_count: number;
   max_runs: number | null;
@@ -78,9 +86,13 @@ export interface CreateScheduledTimerRowInput {
   nextRunAt: number;
   scheduleKind: TimerScheduleKind;
   scheduleDef: TimerScheduleDef;
+  messageKind?: string;
+  channel?: string;
   subject?: string;
   body: string;
+  claimable?: boolean;
   payload?: Record<string, unknown>;
+  meta?: Record<string, unknown>;
   maxRuns?: number;
   expiresAt?: number;
   idempotencyKey?: string;
@@ -92,10 +104,10 @@ export function insertScheduledTimer(input: CreateScheduledTimerRowInput, now =
   getDb().query(`
     INSERT INTO scheduled_timers (
       id, target, created_by, created_by_kind, created_by_scopes, created_by_constraints, delivery_from,
-      created_at, next_run_at, schedule_kind, schedule_def, subject, body, payload, enabled,
+      created_at, next_run_at, schedule_kind, schedule_def, message_kind, channel, subject, body, claimable, payload, meta, enabled,
       run_count, max_runs, expires_at, idempotency_key, correlation_id
     )
-    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, 1, 0, ?, ?, ?, ?)
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, 1, 0, ?, ?, ?, ?)
   `).run(
     id,
     input.target,
@@ -108,9 +120,13 @@ export function insertScheduledTimer(input: CreateScheduledTimerRowInput, now =
     input.nextRunAt,
     input.scheduleKind,
     JSON.stringify(input.scheduleDef),
+    input.messageKind ?? null,
+    input.channel ?? null,
     input.subject ?? null,
     input.body,
+    input.claimable ? 1 : 0,
     JSON.stringify(input.payload ?? {}),
+    JSON.stringify(input.meta ?? {}),
     input.maxRuns ?? null,
     input.expiresAt ?? null,
     input.idempotencyKey ?? null,
@@ -199,20 +215,20 @@ export function completeScheduledTimerRun(input: {
         claimed_by = NULL,
         claim_expires_at = NULL
     WHERE id = ?
-  `).run(runCount, input.now, input.messageId, candidateNextRunAt, enabled ? 1 : 0, input.timer.id);
+      AND claimed_by = ?
+      AND enabled = 1
+  `).run(runCount, input.now, input.messageId, candidateNextRunAt, enabled ? 1 : 0, input.timer.id, input.timer.claimedBy ?? "");
   return getScheduledTimer(input.timer.id)!;
 }
 
 export function recordScheduledTimerFailure(input: {
-  id: string;
+  timer: ScheduledTimer;
   error: string;
   now: number;
   retryMs: number;
   maxFailures: number;
 }): ScheduledTimer | null {
-  const current = getScheduledTimer(input.id);
-  if (!current) return null;
-  const failures = current.consecutiveFailures + 1;
+  const failures = input.timer.consecutiveFailures + 1;
   const enabled = failures < input.maxFailures;
   getDb().query(`
     UPDATE scheduled_timers
@@ -223,17 +239,18 @@ export function recordScheduledTimerFailure(input: {
         claimed_by = NULL,
         claim_expires_at = NULL
     WHERE id = ?
-  `).run(input.error, failures, input.now + input.retryMs, enabled ? 1 : 0, input.id);
-  return getScheduledTimer(input.id);
+      AND claimed_by = ?
+      AND enabled = 1
+  `).run(input.error, failures, input.now + input.retryMs, enabled ? 1 : 0, input.timer.id, input.timer.claimedBy ?? "");
+  return getScheduledTimer(input.timer.id);
 }
 
-export function cancelScheduledTimer(id: string, now = Date.now()): ScheduledTimer | null {
-  const result = getDb().query(`
+export function cancelScheduledTimer(id: string): ScheduledTimer | null {
+  getDb().query(`
     UPDATE scheduled_timers
     SET enabled = 0, claimed_by = NULL, claim_expires_at = NULL, last_error = COALESCE(last_error, 'cancelled')
     WHERE id = ? AND enabled = 1
   `).run(id);
-  if (result.changes === 0) return getScheduledTimer(id);
   return getScheduledTimer(id);
 }
 
@@ -259,9 +276,13 @@ function rowToTimer(row: ScheduledTimerRow): ScheduledTimer {
     nextRunAt: row.next_run_at,
     scheduleKind: row.schedule_kind === "interval" ? "interval" : "once",
     scheduleDef: parseRecord(row.schedule_def) as TimerScheduleDef,
+    messageKind: row.message_kind ?? undefined,
+    channel: row.channel ?? undefined,
     subject: row.subject ?? undefined,
     body: row.body,
+    claimable: row.claimable === 1 ? true : undefined,
     payload: parseRecord(row.payload) ?? {},
+    meta: parseRecord(row.meta) ?? {},
     enabled: row.enabled === 1,
     runCount: row.run_count,
     maxRuns: row.max_runs ?? undefined,

package/src/db/schema.ts

@@ -176,9 +176,13 @@ export function initDb(path: string = "agent-relay.db"): Database {
       next_run_at INTEGER NOT NULL,
       schedule_kind TEXT NOT NULL,
       schedule_def TEXT NOT NULL,
+      message_kind TEXT,
+      channel TEXT,
       subject TEXT,
       body TEXT NOT NULL,
+      claimable INTEGER NOT NULL DEFAULT 0,
       payload TEXT NOT NULL DEFAULT '{}',
+      meta TEXT NOT NULL DEFAULT '{}',
       enabled INTEGER NOT NULL DEFAULT 1,
       run_count INTEGER NOT NULL DEFAULT 0,
       max_runs INTEGER,

package/src/mcp/index.ts

@@ -150,7 +150,7 @@ async function callTool(auth: McpAuthContext, params: unknown): Promise<Record<s
     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); else if (name.startsWith("relay_issue_ref_")) result = relayIssueRefTool(auth, name, args); else if (name.startsWith("relay_issue_association_")) result = relayIssueAssociationTool(auth, name, args); else if (name.startsWith("relay_issue_activity_")) result = relayIssueActivityTool(auth, name, args); else if (name.startsWith("relay_issue_lifecycle_")) result = await relayIssueLifecycleTool(auth, name, args);
-    else if (name === "relay_subscribe" || name === "relay_unsubscribe" || name === "relay_list_subscriptions") result = relayNotificationSubscriptionTool(auth, name, args);
+    else if (name === "relay_subscribe" || name === "relay_unsubscribe" || name === "relay_list_subscriptions" || name === "relay_why_notified" || name === "relay_notification_preview") result = relayNotificationSubscriptionTool(auth, name, args);
     else if (name === "relay_notify_ntfy") result = await relayNotifyNtfy(args);
     else throw new ValidationError(`unknown tool: ${name}`);
 

package/src/mcp/tools-messaging.ts

@@ -54,6 +54,7 @@ export const MESSAGING_TOOLS: ToolDefinition[] = [
         from: { type: "string", description: "Deprecated/optional. Your identity is taken from your auth token; ignored for managed agents. You never need to set this." },
         to: { type: "string", description: "Target: an agent id, label, name, or a unique id segment (e.g. the number part) — resolved automatically. Or a fan-out selector: tag:, cap:, label:, team:, policy:, or broadcast." },
         body: { type: "string" },
+        kind: { type: "string", enum: ["chat", "channel.event", "task", "pair", "control", "system", "session"] },
         subject: { type: "string" },
         channel: { type: "string" },
         claimable: { type: "boolean" },
@@ -226,6 +227,10 @@ function runMcpSend(auth: McpAuthContext, input: SendMessageInput): Message & {
 export function relaySendMessage(auth: McpAuthContext, args: Record<string, unknown>): (Message & { delivery: DeliveryReceipt }) | Record<string, unknown> {
   const attachments = optionalAttachments(args.attachments);
   const payload = payloadWithAttachments(optionalRecord(args.payload, "payload"), attachments);
+  const kind = optionalEnum(args.kind, "kind", ["chat", "channel.event", "task", "pair", "control", "system", "session"] as const);
+  const channel = optionalString(args.channel, "channel", 120);
+  const claimable = optionalBoolean(args.claimable, "claimable");
+  const meta = optionalRecord(args.meta, "meta");
   const deliveryTime = optionalString(args.deliveryTime, "deliveryTime", 80);
   if (deliveryTime) {
     if (!hasScope(auth, "schedule:write")) throw new McpAuthError("deliveryTime requires schedule:write");
@@ -233,9 +238,13 @@ export function relaySendMessage(auth: McpAuthContext, args: Record<string, unkn
       const timer = scheduleTimer({
         target: stringField(args.to, "to", { required: true, max: 200 }),
         at: deliveryTime,
+        kind,
+        channel,
         body: stringField(args.body, "body", { required: true, maxBytes: MAX_BODY_BYTES }),
         subject: optionalString(args.subject, "subject", 200),
+        claimable,
         payload,
+        meta,
         idempotencyKey: optionalString(args.idempotencyKey, "idempotencyKey", 240),
       }, authContextFromMcp({ kind: auth.kind, actor: auth.actor, scopes: auth.scopes, component: auth.component }));
       return { scheduled: true, timer };
@@ -247,14 +256,15 @@ export function relaySendMessage(auth: McpAuthContext, args: Record<string, unkn
   const input: SendMessageInput = {
     from: optionalString(args.from, "from", 200) ?? "",
     to: stringField(args.to, "to", { required: true, max: 200 }),
+    kind,
+    channel,
     body: stringField(args.body, "body", { required: true, maxBytes: MAX_BODY_BYTES }),
     subject: optionalString(args.subject, "subject", 200),
-    channel: optionalString(args.channel, "channel", 120),
-    claimable: optionalBoolean(args.claimable, "claimable"),
+    claimable,
     idempotencyKey: optionalString(args.idempotencyKey, "idempotencyKey", 240),
     attachments,
     payload,
-    meta: optionalRecord(args.meta, "meta"),
+    meta,
   };
   return runMcpSend(auth, input);
 }

package/src/mcp-notification-subscription-tools.ts

@@ -15,10 +15,11 @@ import {
   type NotificationSubscriptionMode,
 } from "./db/notification-subscriptions";
 import { ValidationError } from "./db";
-import { McpAuthError } from "./mcp-errors";
+import { McpAuthError, McpNotFoundError } from "./mcp-errors";
 import { authContextFromMcp } from "./services/auth-context";
 import { cleanString } from "./validation";
-import type { NotificationScope } from "./notification-types";
+import { NOTIFICATION_TYPES, type NotificationScope, type NotificationType } from "./notification-types";
+import { previewNotificationRouting, whyNotified } from "./notification-router";
 
 export const NOTIFICATION_SUBSCRIPTION_TOOLS = [
   {
@@ -68,6 +69,33 @@ export const NOTIFICATION_SUBSCRIPTION_TOOLS = [
       additionalProperties: false,
     },
   },
+  {
+    name: "relay_why_notified",
+    description: "Explain why this caller agent received a delivered notification message.",
+    requiredScopes: ["notifications:read"],
+    inputSchema: {
+      type: "object",
+      properties: {
+        messageId: { type: "number", description: "Delivered Relay message id." },
+      },
+      required: ["messageId"],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "relay_notification_preview",
+    description: "Dry-run notification routing for a type and scope, returning recipients and matched rules without sending.",
+    requiredScopes: ["notifications:read"],
+    inputSchema: {
+      type: "object",
+      properties: {
+        type: { type: "string", enum: NOTIFICATION_TYPES },
+        scope: { type: "object", description: "Notification scope, such as { author, teamId, repoRoot, workspaceId }." },
+      },
+      required: ["type", "scope"],
+      additionalProperties: false,
+    },
+  },
 ] satisfies Array<{ name: string; description: string; requiredScopes: string[]; inputSchema: Record<string, unknown> }>;
 
 type McpAuthLike = Parameters<typeof authContextFromMcp>[0];
@@ -149,6 +177,17 @@ export function relayNotificationSubscriptionTool(
       },
     };
   }
+  if (name === "relay_why_notified") {
+    const explanation = whyNotified(cleanMessageId(args.messageId), agentId);
+    if (!explanation) throw new McpNotFoundError("notification routing explanation not found for this agent/message");
+    return { ...explanation };
+  }
+  if (name === "relay_notification_preview") {
+    return { ...previewNotificationRouting({
+      type: cleanNotificationType(args.type),
+      scope: cleanScope(args.scope) ?? {},
+    }) };
+  }
   throw new ValidationError(`unknown tool: ${name}`);
 }
 
@@ -169,6 +208,20 @@ function cleanScope(value: unknown): Partial<NotificationScope> | null {
   return value as Partial<NotificationScope>;
 }
 
+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 cleanMessageId(value: unknown): number {
+  if (typeof value !== "number" || !Number.isSafeInteger(value) || value <= 0) {
+    throw new ValidationError("messageId must be a positive integer");
+  }
+  return value;
+}
+
 function cleanChildStreams(value: unknown): ChildStream[] {
   if (!Array.isArray(value) || value.length === 0) throw new ValidationError("streams must be a non-empty array");
   return [...new Set(value.map(cleanChildStream))];