agent-relay-server 0.59.0 → 0.60.0

package/src/agent-lifecycle-events.ts

@@ -1,6 +1,6 @@
 import { emitRelayEvent } from "./events";
 import { getNotificationsConfig } from "./config-store";
-import { notifySystemMessage } from "./notify";
+import { routeNotification } from "./notification-router";
 import { getAgent } from "./db";
 import type { AgentCard } from "./types";
 
@@ -56,11 +56,16 @@ export function notifyAgentReady(childId: string): void {
 
   const config = getNotificationsConfig();
   if (!config.enabled || !config.agentReady) return;
-  notifySystemMessage(parent, {
-    subject: "Spawned agent ready",
-    body: `✅ Your spawned agent ${describe(child)} is ready and idle — send it work with relay_send_message to \`${childId}\`.`,
-    payload: { kind: "agent.ready", agentId: childId, parent, provider: providerOf(child), spawnRequestId: spawnRequestIdOf(child) },
-    replyExpected: false,
+  routeNotification({
+    type: "agent.ready",
+    scope: { agentId: childId, parent },
+    recipients: [parent],
+    message: {
+      subject: "Spawned agent ready",
+      body: `✅ Your spawned agent ${describe(child)} is ready and idle — send it work with relay_send_message to \`${childId}\`.`,
+      payload: { kind: "agent.ready", agentId: childId, parent, provider: providerOf(child), spawnRequestId: spawnRequestIdOf(child) },
+      replyExpected: false,
+    },
   });
 }
 
@@ -85,11 +90,16 @@ export function notifyAgentOffline(childId: string, reason: string): void {
       data: { agentId: childId, parent, reason, provider: providerOf(child), spawnRequestId: spawnRequestIdOf(child) },
     });
     if (!config.enabled || !config.agentExited) return;
-    notifySystemMessage(parent, {
-      subject: "Spawned agent exited",
-      body: `⏹ Your spawned agent ${describe(child)} exited — ${reason}.`,
-      payload: { kind: "agent.exited", agentId: childId, parent, reason },
-      replyExpected: false,
+    routeNotification({
+      type: "agent.exited",
+      scope: { agentId: childId, parent },
+      recipients: [parent],
+      message: {
+        subject: "Spawned agent exited",
+        body: `⏹ Your spawned agent ${describe(child)} exited — ${reason}.`,
+        payload: { kind: "agent.exited", agentId: childId, parent, reason },
+        replyExpected: false,
+      },
     });
     return;
   }
@@ -101,11 +111,16 @@ export function notifyAgentOffline(childId: string, reason: string): void {
     data: { agentId: childId, parent, reason, provider: providerOf(child), spawnRequestId: spawnRequestIdOf(child), neverReady: true },
   });
   if (!config.enabled || !config.agentSpawnFailed) return;
-  notifySystemMessage(parent, {
-    subject: "Spawn failed",
-    body: `❌ Your spawned agent ${describe(child)} went offline before ever becoming ready — ${reason}. Likely a crash-loop, onboarding gate, or bad launch; call relay_spawn_targets to re-check provider availability before retrying.`,
-    payload: { kind: "agent.spawn_failed", agentId: childId, parent, reason },
-    replyExpected: false,
+  routeNotification({
+    type: "agent.spawn_failed",
+    scope: { agentId: childId, parent },
+    recipients: [parent],
+    message: {
+      subject: "Spawn failed",
+      body: `❌ Your spawned agent ${describe(child)} went offline before ever becoming ready — ${reason}. Likely a crash-loop, onboarding gate, or bad launch; call relay_spawn_targets to re-check provider availability before retrying.`,
+      payload: { kind: "agent.spawn_failed", agentId: childId, parent, reason },
+      replyExpected: false,
+    },
   });
 }
 
@@ -123,11 +138,16 @@ export function notifyAgentSpawnFailed(input: { parent: string; spawnRequestId?:
   });
   const config = getNotificationsConfig();
   if (!config.enabled || !config.agentSpawnFailed) return;
-  notifySystemMessage(input.parent, {
-    subject: "Spawn failed",
-    body: `❌ Your spawn request${input.spawnRequestId ? ` \`${input.spawnRequestId}\`` : ""} failed — ${input.reason}. Call relay_spawn_targets to check live provider/host availability before retrying.`,
-    payload: { kind: "agent.spawn_failed", parent: input.parent, spawnRequestId: input.spawnRequestId, provider: input.provider, reason: input.reason },
-    replyExpected: false,
+  routeNotification({
+    type: "agent.spawn_failed",
+    scope: { parent: input.parent },
+    recipients: [input.parent],
+    message: {
+      subject: "Spawn failed",
+      body: `❌ Your spawn request${input.spawnRequestId ? ` \`${input.spawnRequestId}\`` : ""} failed — ${input.reason}. Call relay_spawn_targets to check live provider/host availability before retrying.`,
+      payload: { kind: "agent.spawn_failed", parent: input.parent, spawnRequestId: input.spawnRequestId, provider: input.provider, reason: input.reason },
+      replyExpected: false,
+    },
   });
 }
 

package/src/branch-landed.ts

@@ -1,9 +1,16 @@
 import { emitRelayEvent } from "./events";
 import { getNotificationsConfig } from "./config-store";
-import { notifySystemMessage } from "./notify";
-import { createActivityEvent, listAgents, updateWorkspaceStatus } from "./db";
-import { isAgentOnline } from "./agent-ref";
-import type { AgentCard, WorkspaceMergePreview, WorkspaceRecord } from "./types";
+import { routeNotification, INFORMATIONAL_TTL_MS } from "./notification-router";
+import { registerDefaultAudienceRules, resolveAudience, audiencePredicates } from "./notification-rules";
+import { createActivityEvent, getAgent, updateWorkspaceStatus } from "./db";
+import type { WorkspaceMergePreview, WorkspaceRecord } from "./types";
+
+// #444 — branch.landed is the first rule-driven type: the on-main "merged" fan-out audience comes
+// from the #442 engine, not a hand-rolled agentsOnMain scan. onRepoRoot delivers online agents in
+// the main checkout (author excluded — they get the direct store-ahead copy below); differentTeam
+// then scopes the fan-out to the land's team, so a Team-A land no longer wakes Team-B agents sharing
+// the main checkout (epic #440's dogfooded symptom). A teamless author/agent keeps prior reach.
+registerDefaultAudienceRules("branch.landed", [audiencePredicates.onRepoRoot(), audiencePredicates.differentTeam()]);
 
 export interface BranchLandedInput {
   /**
@@ -88,27 +95,44 @@ export function notifyBranchLanded(input: BranchLandedInput): void {
     const continueLabel = input.newBranch
       ? ` You're now on \`${input.newBranch}\` — keep working there.`
       : " Worktree reclaimed.";
-    notifySystemMessage(author, {
-      subject: "Your branch landed",
-      body: `✅ ${branchLabel} landed on \`${base}\`${shaLabel}${subjectLabel}.${publishLabel}${continueLabel}`,
-      payload,
-      replyExpected: false,
+    // Durable (ttl null): the author's own branch landing must reach them even after they go
+    // offline (store-ahead #234) — not a bystander notice that goes stale.
+    routeNotification({
+      type: "branch.landed",
+      scope: { author, repoRoot: workspace.repoRoot, workspaceId: workspace.id },
+      recipients: [author],
+      ttlMs: null,
+      message: {
+        subject: "Your branch landed",
+        body: `✅ ${branchLabel} landed on \`${base}\`${shaLabel}${subjectLabel}.${publishLabel}${continueLabel}`,
+        payload,
+        replyExpected: false,
+      },
     });
   }
 
-  // Agents on `main` — those whose cwd IS the main checkout (not an isolated worktree) —
-  // get a live "merged" notice so a long-lived main agent's context stays current as work
-  // lands under it (#239). Online-only: a stale/exited main session needs no wake, and
-  // store-ahead to it would just pile up noise. The author is in a worktree (cwd ≠ repoRoot)
-  // so it's naturally excluded; guard anyway for shared-mode owners.
-  const branchLabel = landedBranch ? `\`${landedBranch}\`` : "A branch";
-  const authorLabel = author ? ` by \`${author}\`` : "";
-  for (const agent of agentsOnMain(workspace.repoRoot, author)) {
-    notifySystemMessage(agent.id, {
-      subject: `Merged to ${base}`,
-      body: `🔀 ${branchLabel}${authorLabel} merged to \`${base}\`${shaLabel}${subjectLabel}.${publishLabel}`,
-      payload,
-      replyExpected: false,
+  // On-main "merged" fan-out — a live notice so a long-lived main agent's context stays current as
+  // work lands under it (#239). Recipients now come from the #442 rule engine (registered above):
+  // 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,
+        replyExpected: false,
+      },
     });
   }
 }
@@ -148,16 +172,3 @@ export function reconcileLandedWorkspace(ws: WorkspaceRecord, preview: Workspace
     // Notification is best-effort; the merged status + activity event still stand.
   }
 }
-
-// An agent is "on `main`" when its registered cwd equals the repo's main checkout — i.e. it
-// works in the base, not an isolated worktree. Excludes the author, pseudo agents (system/
-// user), channels, and offline sessions.
-function agentsOnMain(repoRoot: string, author: string | undefined): AgentCard[] {
-  return listAgents().filter((a) => {
-    if (a.id === author || a.id === "system" || a.id === "user") return false;
-    if (a.kind === "channel" || a.meta?.kind === "channel") return false;
-    const cwd = a.meta?.cwd;
-    if (typeof cwd !== "string" || cwd !== repoRoot) return false;
-    return isAgentOnline(a);
-  });
-}

package/src/channel-target.ts

@@ -23,3 +23,13 @@ export function parseChannelRouteTarget(target: string): ChannelRouteTarget {
   if (target.startsWith("orchestrator:")) return { type: "orchestrator", id: target.slice("orchestrator:".length) };
   return { type: "agent", id: target };
 }
+
+// A fan-out target addresses MANY agents (broadcast / tag / cap / label / team / pool) rather than
+// one. #451 uses this to scope the default message TTL: a stale fan-out message must not wake a
+// late-joining agent, whereas a direct DM (and `policy:`, which resolves to one running agent or
+// queues with its own expiry) is store-ahead and never auto-expires. Built on the one parser above
+// so the prefix set can't drift from route resolution.
+export function isFanoutTarget(target: string): boolean {
+  const { type } = parseChannelRouteTarget(target);
+  return type === "broadcast" || type === "tag" || type === "capability" || type === "label" || type === "team" || type === "pool";
+}

package/src/config.ts

@@ -20,6 +20,11 @@ function envPositiveInt(name: string, fallback: number): number {
 }
 
 export const STALE_TTL_MS = envPositiveInt("STALE_TTL_MS", 120_000); // 2min without heartbeat → offline
+// #451 — default TTL for fire-and-forget FAN-OUT messages (broadcast/tag/cap/label/team) that the
+// sender didn't bound. A stale fan-out push must not wake an agent that matches the target hours
+// later (the cold-session-woken-by-old-coordination-thread bug). Direct DMs, reply-obligations, and
+// claimable work are exempt (never auto-expire) so store-ahead (#234) still delivers them.
+export const DEFAULT_FANOUT_TTL_SECONDS = envPositiveInt("AGENT_RELAY_FANOUT_TTL_SECONDS", 2 * 60 * 60); // 2h
 export const OFFLINE_PRUNE_MS = envPositiveInt("OFFLINE_PRUNE_MS", DAY_MS); // 24h offline → delete
 export const REAP_INTERVAL_MS = envPositiveInt("REAP_INTERVAL_MS", 60_000); // reaper cadence
 export const CLAIM_LEASE_MS = envPositiveInt("AGENT_RELAY_CLAIM_LEASE_MS", 1_800_000); // 30min claim lease

package/src/context-advisory.ts

@@ -1,7 +1,7 @@
 import { getNotificationsConfig } from "./config-store";
 import { getDb } from "./db/connection.ts";
 import { emitRelayEvent } from "./events";
-import { notifySystemMessage } from "./notify";
+import { routeNotification } from "./notification-router";
 import type { AgentCard, Command, ContextState } from "./types";
 
 interface ContextAdvisoryInput {
@@ -38,11 +38,18 @@ function notifyContextAdvisory(input: ContextAdvisoryInput): void {
   const config = getNotificationsConfig();
   if (!config.enabled || !config.contextThreshold.enabled) return;
 
-  notifySystemMessage(input.agentId, {
-    subject: "Context threshold reached",
-    body: `Context advisory: ${formatTokens(input.tokens)} / ${formatTokens(input.windowTokens)} tokens used (${input.percent}% of window, ${input.band}% band). Compact at a clean seam before the ${input.hardBackstopPercent}% hard backstop may request compaction.`,
-    payload,
-    replyExpected: false,
+  // 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({
+    type: "agent.context_threshold",
+    scope: { agentId: input.agentId },
+    recipients: [input.agentId],
+    message: {
+      subject: "Context threshold reached",
+      body: `Context advisory: ${formatTokens(input.tokens)} / ${formatTokens(input.windowTokens)} tokens used (${input.percent}% of window, ${input.band}% band). Compact at a clean seam before the ${input.hardBackstopPercent}% hard backstop may request compaction.`,
+      payload,
+      replyExpected: false,
+    },
   });
 }
 

package/src/db/message-reads.ts

@@ -204,6 +204,12 @@ export function pollMessages(query: PollQuery): Message[] {
   }
   conditions.push("delivery_status != 'queued' AND delivery_status NOT IN ('failed', 'dead')");
 
+  // #451 — never surface a message past its TTL: a stale fan-out notification must not wake an
+  // agent that matches its target long after it was sent. NULL max_age_seconds never expires
+  // (direct DMs, reply-obligations, claimable work — store-ahead #234 still delivers those).
+  conditions.push("(max_age_seconds IS NULL OR created_at + max_age_seconds * 1000 > ?)");
+  params.push(Date.now());
+
   // A claimable message is available to this agent when it is non-claimable, currently held by
   // THIS agent, or unclaimed/expired AND its task is not already closed. The closed-task guard
   // must cover BOTH the null-claim and the expired-claim branch: when a managed agent is

package/src/db/messages.ts

@@ -12,8 +12,9 @@ import {
   parseRuntimePackage,
   type RuntimeContracts,
 } from "../contracts";
-import { STALE_TTL_MS, DAY_MS, CLAIM_LEASE_MS, POOL_CLAIM_LEASE_MS, WORKSPACE_MERGE_LEASE_MS } from "../config";
+import { STALE_TTL_MS, DAY_MS, CLAIM_LEASE_MS, POOL_CLAIM_LEASE_MS, WORKSPACE_MERGE_LEASE_MS, DEFAULT_FANOUT_TTL_SECONDS } from "../config";
 import { matchAgents } from "../agent-ref";
+import { isFanoutTarget } from "../channel-target";
 import { getAgent, validateAgentSession } from "./agents.ts";
 import { cleanAttachmentRefs, linkAttachmentRefs, validateAttachmentRefs } from "./artifacts.ts";
 import { ClaimError, ValidationError, getDb } from "./connection.ts";
@@ -247,6 +248,10 @@ export function sendMessageWithResult(input: SendMessageInput): { message: Messa
   const policyName = policyNameFromTarget(input.to);
   let deliveryStatus: Message["deliveryStatus"] = "pending";
   let queuedAt: number | null = null;
+  // Distinguish "unspecified" (apply the #451 fan-out default below) from an explicit `null`
+  // (authoritative never-expire — routeNotification sets this for store-ahead notification types,
+  // and the baseline must not override it). Both store as NULL, but only unspecified gets a default.
+  const ttlUnspecified = input.maxAgeSeconds === undefined;
   let maxAgeSeconds = input.maxAgeSeconds ?? null;
   let resolvedToAgent: string | null = null;
 
@@ -260,6 +265,16 @@ export function sendMessageWithResult(input: SendMessageInput): { message: Messa
     }
   }
 
+  // #451 — moderate default TTL for fire-and-forget FAN-OUT messages the sender didn't bound, so a
+  // stale broadcast/tag/cap/label/team push can't wake a late-joining agent hours later. Exempt
+  // (never auto-expire, preserving store-ahead #234): direct DMs and policy targets (single
+  // recipient), reply-obligations (replyExpected !== false), claimable work, and any message that
+  // already carried an explicit TTL — including an explicit `null` from routeNotification, whose
+  // per-type decision (e.g. a store-ahead `plan.bound_agent_exited` to `team:`) must win here.
+  if (ttlUnspecified && input.replyExpected === false && !claimable && isFanoutTarget(input.to)) {
+    maxAgeSeconds = DEFAULT_FANOUT_TTL_SECONDS;
+  }
+
   const id = getDb().transaction(() => {
     const result = insert.run({
       $from: input.from,

package/src/db/migrations.ts

@@ -449,6 +449,21 @@ export function applyMigrations(): void {
     getDb().run("ALTER TABLE agents ADD COLUMN team_id TEXT");
   }
   getDb().run("CREATE INDEX IF NOT EXISTS idx_agents_team ON agents(team_id)");
+  getDb().run(`
+    CREATE TABLE IF NOT EXISTS notification_subscriptions (
+      id TEXT PRIMARY KEY,
+      agent_id TEXT NOT NULL REFERENCES agents(id) ON DELETE CASCADE,
+      type TEXT NOT NULL,
+      mode TEXT NOT NULL CHECK (mode IN ('opt_in', 'opt_out', 'mute')),
+      scope_match TEXT,
+      created_at INTEGER NOT NULL
+    )
+  `);
+  getDb().run("CREATE INDEX IF NOT EXISTS idx_notification_subscriptions_agent ON notification_subscriptions(agent_id, type)");
+  getDb().run(`
+    CREATE UNIQUE INDEX IF NOT EXISTS idx_notification_subscriptions_unique
+    ON notification_subscriptions(agent_id, type, mode, coalesce(scope_match, ''))
+  `);
   getDb().run(`
     CREATE TABLE IF NOT EXISTS context_snapshots (
       id INTEGER PRIMARY KEY AUTOINCREMENT,

package/src/db/notification-subscriptions.ts

@@ -0,0 +1,198 @@
+import { randomUUID } from "node:crypto";
+import { isRecord } from "agent-relay-sdk";
+import { DEFAULT_TTL_MS, type NotificationScope, type NotificationType } from "../notification-router";
+import { setSubscriptionRules, type NotificationRule, type NotificationRuleContext, type RuleDecision } from "../notification-rules";
+import type { AgentCard } from "../types";
+import { parseJson } from "../utils";
+import { getDb, ValidationError } from "./connection";
+
+export const NOTIFICATION_SUBSCRIPTION_TYPES = ["*", ...Object.keys(DEFAULT_TTL_MS)] as Array<NotificationType | "*">;
+export const NOTIFICATION_SUBSCRIPTION_MODES = ["opt_in", "opt_out", "mute"] as const;
+
+export type NotificationSubscriptionType = NotificationType | "*";
+export type NotificationSubscriptionMode = (typeof NOTIFICATION_SUBSCRIPTION_MODES)[number];
+
+export interface NotificationSubscription {
+  id: string;
+  agentId: string;
+  type: NotificationSubscriptionType;
+  mode: NotificationSubscriptionMode;
+  scopeMatch: Partial<NotificationScope> | null;
+  createdAt: number;
+}
+
+interface NotificationSubscriptionRow {
+  id: string;
+  agent_id: string;
+  type: string;
+  mode: string;
+  scope_match: string | null;
+  created_at: number;
+}
+
+const SCOPE_KEYS = ["author", "agentId", "parent", "teamId", "planId", "repoRoot", "workspaceId", "paths"] as const;
+
+export function addSubscription(input: {
+  agentId: string;
+  type: NotificationSubscriptionType;
+  mode: NotificationSubscriptionMode;
+  scopeMatch?: Partial<NotificationScope> | null;
+  now?: number;
+}): NotificationSubscription {
+  const agentId = cleanAgentId(input.agentId);
+  const type = cleanSubscriptionType(input.type);
+  const mode = cleanSubscriptionMode(input.mode);
+  const scopeMatch = normalizeScopeMatch(input.scopeMatch);
+  const now = input.now ?? Date.now();
+
+  getDb().query(`
+    DELETE FROM notification_subscriptions
+    WHERE agent_id = ? AND type = ? AND mode = ? AND coalesce(scope_match, '') = coalesce(?, '')
+  `).run(agentId, type, mode, scopeMatch);
+
+  const id = `nsub_${randomUUID()}`;
+  getDb().query(`
+    INSERT INTO notification_subscriptions (id, agent_id, type, mode, scope_match, created_at)
+    VALUES (?, ?, ?, ?, ?, ?)
+  `).run(id, agentId, type, mode, scopeMatch, now);
+
+  return getSubscription(id)!;
+}
+
+export function removeSubscription(input: {
+  agentId: string;
+  id?: string;
+  type?: NotificationSubscriptionType;
+  mode?: NotificationSubscriptionMode;
+  scopeMatch?: Partial<NotificationScope> | null;
+}): number {
+  const agentId = cleanAgentId(input.agentId);
+  const conditions = ["agent_id = ?"];
+  const params: any[] = [agentId];
+
+  if (input.id) {
+    conditions.push("id = ?");
+    params.push(input.id);
+  }
+  if (input.type) {
+    conditions.push("type = ?");
+    params.push(cleanSubscriptionType(input.type));
+  }
+  if (input.mode) {
+    conditions.push("mode = ?");
+    params.push(cleanSubscriptionMode(input.mode));
+  }
+  if (Object.prototype.hasOwnProperty.call(input, "scopeMatch")) {
+    conditions.push("coalesce(scope_match, '') = coalesce(?, '')");
+    params.push(normalizeScopeMatch(input.scopeMatch));
+  }
+  if (conditions.length === 1) throw new ValidationError("id or type required");
+
+  return getDb().query(`DELETE FROM notification_subscriptions WHERE ${conditions.join(" AND ")}`).run(...params).changes;
+}
+
+export function listSubscriptions(agentId: string): NotificationSubscription[] {
+  const rows = getDb().query(`
+    SELECT * FROM notification_subscriptions
+    WHERE agent_id = ?
+    ORDER BY created_at ASC, id ASC
+  `).all(cleanAgentId(agentId)) as NotificationSubscriptionRow[];
+  return rows.map(rowToSubscription);
+}
+
+export function subscriptionDecisionFor(agent: AgentCard, ctx: NotificationRuleContext): RuleDecision {
+  const rows = getDb().query(`
+    SELECT * FROM notification_subscriptions
+    WHERE agent_id = ? AND (type = ? OR type = '*')
+    ORDER BY created_at ASC, id ASC
+  `).all(agent.id, ctx.type) as NotificationSubscriptionRow[];
+
+  let decision: RuleDecision = "abstain";
+  for (const row of rows) {
+    const subscription = rowToSubscription(row);
+    if (!scopeMatches(subscription.scopeMatch, ctx.scope)) continue;
+    decision = subscription.mode === "opt_in" ? "deliver" : "suppress";
+  }
+  return decision;
+}
+
+const subscriptionRule: NotificationRule = {
+  name: "subscription:store",
+  evaluate: subscriptionDecisionFor,
+};
+
+export function installNotificationSubscriptionRule(): void {
+  setSubscriptionRules([subscriptionRule]);
+}
+
+function getSubscription(id: string): NotificationSubscription | null {
+  const row = getDb().query("SELECT * FROM notification_subscriptions WHERE id = ?").get(id) as NotificationSubscriptionRow | undefined;
+  return row ? rowToSubscription(row) : null;
+}
+
+export function cleanSubscriptionType(value: unknown): NotificationSubscriptionType {
+  if (typeof value !== "string" || !NOTIFICATION_SUBSCRIPTION_TYPES.includes(value as NotificationSubscriptionType)) {
+    throw new ValidationError(`type must be one of: ${NOTIFICATION_SUBSCRIPTION_TYPES.join(", ")}`);
+  }
+  return value as NotificationSubscriptionType;
+}
+
+export function cleanSubscriptionMode(value: unknown): NotificationSubscriptionMode {
+  if (typeof value !== "string" || !NOTIFICATION_SUBSCRIPTION_MODES.includes(value as NotificationSubscriptionMode)) {
+    throw new ValidationError(`mode must be one of: ${NOTIFICATION_SUBSCRIPTION_MODES.join(", ")}`);
+  }
+  return value as NotificationSubscriptionMode;
+}
+
+function cleanAgentId(value: unknown): string {
+  if (typeof value !== "string" || !value.trim()) throw new ValidationError("agentId required");
+  return value.trim();
+}
+
+function normalizeScopeMatch(scope: Partial<NotificationScope> | null | undefined): string | null {
+  if (scope === undefined || scope === null) return null;
+  if (!isRecord(scope)) throw new ValidationError("scope must be an object");
+  const normalized: Record<string, unknown> = {};
+  for (const key of SCOPE_KEYS) {
+    const value = scope[key];
+    if (value === undefined || value === null) continue;
+    if (key === "paths") {
+      if (!Array.isArray(value) || value.some((item) => typeof item !== "string")) {
+        throw new ValidationError("scope.paths must be an array of strings");
+      }
+      const paths = [...new Set(value.map((item) => item.trim()).filter(Boolean))].sort();
+      if (paths.length) normalized.paths = paths;
+      continue;
+    }
+    if (typeof value !== "string" || !value.trim()) throw new ValidationError(`scope.${key} must be a string`);
+    normalized[key] = value.trim();
+  }
+  return Object.keys(normalized).length ? JSON.stringify(normalized) : null;
+}
+
+function rowToSubscription(row: NotificationSubscriptionRow): NotificationSubscription {
+  return {
+    id: row.id,
+    agentId: row.agent_id,
+    type: cleanSubscriptionType(row.type),
+    mode: cleanSubscriptionMode(row.mode),
+    scopeMatch: parseJson<Partial<NotificationScope> | null>(row.scope_match, null),
+    createdAt: row.created_at,
+  };
+}
+
+function scopeMatches(match: Partial<NotificationScope> | null, scope: NotificationScope): boolean {
+  if (!match) return true;
+  const actual = scope as Record<string, unknown>;
+  for (const [key, expected] of Object.entries(match)) {
+    const value = actual[key];
+    if (Array.isArray(expected)) {
+      if (!Array.isArray(value)) return false;
+      const actualSet = new Set(value.filter((item): item is string => typeof item === "string"));
+      if (!expected.every((item) => actualSet.has(item))) return false;
+      continue;
+    }
+    if (value !== expected) return false;
+  }
+  return true;
+}

package/src/db/schema.ts

@@ -110,6 +110,17 @@ export function initDb(path: string = "agent-relay.db"): Database {
       last_seen INTEGER NOT NULL,
       created_at INTEGER NOT NULL
     );
+    CREATE TABLE IF NOT EXISTS notification_subscriptions (
+      id TEXT PRIMARY KEY,
+      agent_id TEXT NOT NULL REFERENCES agents(id) ON DELETE CASCADE,
+      type TEXT NOT NULL,
+      mode TEXT NOT NULL CHECK (mode IN ('opt_in', 'opt_out', 'mute')),
+      scope_match TEXT,
+      created_at INTEGER NOT NULL
+    );
+    CREATE INDEX IF NOT EXISTS idx_notification_subscriptions_agent ON notification_subscriptions(agent_id, type);
+    CREATE UNIQUE INDEX IF NOT EXISTS idx_notification_subscriptions_unique
+      ON notification_subscriptions(agent_id, type, mode, coalesce(scope_match, ''));
     CREATE TABLE IF NOT EXISTS messages (
       id INTEGER PRIMARY KEY AUTOINCREMENT,
       from_agent TEXT NOT NULL,

package/src/index.ts

@@ -10,6 +10,7 @@ import { getLifecycleManager } from "./lifecycle-manager";
 import { getCompactionWatch } from "./compaction-watch";
 import { getConfig, setConfig } from "./config-store";
 import { startConnectorStatusPoller } from "./connectors";
+import { installNotificationSubscriptionRule } from "./db/notification-subscriptions";
 import { startPlanLiveBindings } from "./services/plan-live-bindings";
 import { resolve, sep } from "path";
 import { gzipSync, brotliCompressSync, constants as zlibConstants } from "node:zlib";
@@ -74,6 +75,7 @@ function startServer(): void {
 
   assertSafeNetworkConfig(HOST);
   initDb(DB_PATH);
+  installNotificationSubscriptionRule();
   startPlanLiveBindings();
   getLifecycleManager().start();
   getCompactionWatch().start();