agent-relay-server 0.72.0 → 0.73.0

package/src/db/messages.ts

@@ -22,6 +22,7 @@ import { enforceQueueLimit, isChannelAgentId, matchingDeliveryAgents } from "./d
 import { MSG_SELECT, normalizeReactionEmoji, rowToMessage } from "./mappers.ts";
 import { claimMessageRow } from "./message-claims.ts";
 import { getMessage } from "./message-queries.ts";
+import { childStreamSubscribed, type ChildStream } from "./notification-subscriptions.ts";
 import { runningAgentForPolicy } from "./policy-runtime.ts";
 import { getTask, releaseExpiredClaims } from "./tasks.ts";
 import { insertTaskEvent } from "./task-core.ts";
@@ -199,6 +200,14 @@ function isFinalSessionResponse(session: Record<string, unknown>): boolean {
   return session.type === "response" && session.final === true;
 }
 
+function childStreamForSession(session: Record<string, unknown>): ChildStream | null {
+  if (session.type === "response") return "responses";
+  if (session.type === "tool") return "toolCalls";
+  if (session.type === "reasoning") return "reasoning";
+  if (session.type === "narration" || session.type === "narrative") return "narrative";
+  return null;
+}
+
 function captureTurnId(capture: Record<string, unknown>): string | undefined {
   return stringValue(capture.turnId);
 }
@@ -215,6 +224,21 @@ function lineageResponseReportKey(message: Message, session: Record<string, unkn
   return lineageResponseReportKeyForTurn(message.from, lineageResponseTurnId(message, session));
 }
 
+function lineageStreamTurnId(message: Message, session: Record<string, unknown>): string {
+  return stringValue(session.turnId) ?? `message-${message.id}`;
+}
+
+function lineageStreamEventId(message: Message, session: Record<string, unknown>): string {
+  const occurredAt = message.occurredAt ?? message.createdAt;
+  const stepId = stringValue(session.stepId);
+  return stepId ? `${stepId}:${occurredAt}` : `message:${occurredAt}`;
+}
+
+function lineageStreamReportKey(message: Message, session: Record<string, unknown>, stream: ChildStream): string {
+  if (stream === "responses") return lineageResponseReportKey(message, session);
+  return `${stream}-report:${message.from}:${lineageStreamTurnId(message, session)}:${lineageStreamEventId(message, session)}`;
+}
+
 function findLineageReportByTurn(input: {
   from: string;
   to: string;
@@ -312,39 +336,45 @@ function findRecentExplicitLineageDuplicate(input: {
 export function promoteLineageCapturedResponse(message: Message): { message: Message; created: boolean } | null {
   if (message.kind !== "session") return null;
   const session = sessionMeta(message);
-  if (!session || !isFinalSessionResponse(session)) return null;
+  if (!session) return null;
+  const stream = childStreamForSession(session);
+  if (!stream) return null;
+  if (stream === "responses" && !isFinalSessionResponse(session)) return null;
   const child = getAgent(message.from);
   const parent = child?.spawnedBy;
   if (!parent) return null;
+  if (stream !== "responses" && !childStreamSubscribed({ parentId: parent, child, stream })) return null;
 
-  const idempotencyKey = lineageResponseReportKey(message, session);
+  const idempotencyKey = lineageStreamReportKey(message, session, stream);
   const existing = findMessageByIdempotencyKey(message.from, idempotencyKey);
   if (existing) return { message: existing, created: false };
-  const turnId = captureTurnId(session);
-  if (turnId) {
-    const crossKeyDuplicate = findLineageReportByTurn({
+  if (stream === "responses") {
+    const turnId = captureTurnId(session);
+    if (turnId) {
+      const crossKeyDuplicate = findLineageReportByTurn({
+        from: message.from,
+        to: parent,
+        turnId,
+        since: message.createdAt - LINEAGE_REPORT_DUPLICATE_WINDOW_MS,
+      });
+      if (crossKeyDuplicate) return { message: crossKeyDuplicate, created: false };
+    }
+
+    const duplicate = findRecentExplicitLineageDuplicate({
       from: message.from,
       to: parent,
-      turnId,
+      body: message.body,
       since: message.createdAt - LINEAGE_REPORT_DUPLICATE_WINDOW_MS,
     });
-    if (crossKeyDuplicate) return { message: crossKeyDuplicate, created: false };
-  }
-
-  const duplicate = findRecentExplicitLineageDuplicate({
-    from: message.from,
-    to: parent,
-    body: message.body,
-    since: message.createdAt - LINEAGE_REPORT_DUPLICATE_WINDOW_MS,
-  });
-  if (duplicate && !responseCaptureMeta(duplicate)) {
-    getDb().query(`
-      UPDATE messages
-      SET idempotency_key = coalesce(idempotency_key, ?),
-          payload = ?
-      WHERE id = ?
-    `).run(idempotencyKey, JSON.stringify({ ...(duplicate.payload ?? {}), responseCapture: { ...session } }), duplicate.id);
-    return { message: getMessage(duplicate.id) ?? duplicate, created: false };
+    if (duplicate && !responseCaptureMeta(duplicate)) {
+      getDb().query(`
+        UPDATE messages
+        SET idempotency_key = coalesce(idempotency_key, ?),
+            payload = ?
+        WHERE id = ?
+      `).run(idempotencyKey, JSON.stringify({ ...(duplicate.payload ?? {}), responseCapture: { ...session } }), duplicate.id);
+      return { message: getMessage(duplicate.id) ?? duplicate, created: false };
+    }
   }
 
   return sendMessageWithResult({
@@ -354,7 +384,9 @@ export function promoteLineageCapturedResponse(message: Message): { message: Mes
     body: message.body,
     replyExpected: false,
     idempotencyKey,
-    payload: { responseCapture: { ...session } },
+    payload: stream === "responses"
+      ? { responseCapture: { ...session } }
+      : { childStreamCapture: { stream, ...session } },
     occurredAt: message.occurredAt ?? message.createdAt,
   });
 }

package/src/db/notification-subscriptions.ts

@@ -1,16 +1,34 @@
 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 { DEFAULT_TTL_MS, type NotificationScope, type NotificationType } from "../notification-types";
 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 CHILD_STREAMS = ["responses", "toolCalls", "reasoning", "narrative"] as const;
+const CONFIGURABLE_CHILD_STREAMS = ["toolCalls", "reasoning", "narrative"] as const;
+export type ChildStream = (typeof CHILD_STREAMS)[number];
+export type ConfigurableChildStream = (typeof CONFIGURABLE_CHILD_STREAMS)[number];
+type ChildStreamSubscriptionType = `child_stream.${ConfigurableChildStream}`;
+
+const CHILD_STREAM_SUBSCRIPTION_TYPES = CONFIGURABLE_CHILD_STREAMS.map(
+  (stream) => `child_stream.${stream}` as ChildStreamSubscriptionType,
+);
+export const NOTIFICATION_SUBSCRIPTION_TYPES = [
+  "*",
+  ...Object.keys(DEFAULT_TTL_MS),
+  ...CHILD_STREAM_SUBSCRIPTION_TYPES,
+] as Array<NotificationSubscriptionType>;
 export const NOTIFICATION_SUBSCRIPTION_MODES = ["opt_in", "opt_out", "mute"] as const;
 
-type NotificationSubscriptionType = NotificationType | "*";
+type NotificationSubscriptionType = NotificationType | "*" | ChildStreamSubscriptionType;
 export type NotificationSubscriptionMode = (typeof NOTIFICATION_SUBSCRIPTION_MODES)[number];
+type SubscriptionRuleDecision = "deliver" | "suppress" | "abstain";
+interface SubscriptionRuleContext {
+  type: NotificationType;
+  scope: NotificationScope;
+  now: number;
+}
 
 interface NotificationSubscription {
   id: string;
@@ -100,14 +118,14 @@ export function listSubscriptions(agentId: string): NotificationSubscription[] {
   return rows.map(rowToSubscription);
 }
 
-export function subscriptionDecisionFor(agent: AgentCard, ctx: NotificationRuleContext): RuleDecision {
+export function subscriptionDecisionFor(agent: AgentCard, ctx: SubscriptionRuleContext): SubscriptionRuleDecision {
   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";
+  let decision: SubscriptionRuleDecision = "abstain";
   for (const row of rows) {
     const subscription = rowToSubscription(row);
     if (!scopeMatches(subscription.scopeMatch, ctx.scope)) continue;
@@ -116,13 +134,51 @@ export function subscriptionDecisionFor(agent: AgentCard, ctx: NotificationRuleC
   return decision;
 }
 
-const subscriptionRule: NotificationRule = {
-  name: "subscription:store",
-  evaluate: subscriptionDecisionFor,
-};
+export function childStreamSubscriptionType(stream: ConfigurableChildStream): ChildStreamSubscriptionType {
+  return `child_stream.${stream}`;
+}
+
+export function childStreamFromSubscriptionType(type: NotificationSubscriptionType): ConfigurableChildStream | null {
+  if (!type.startsWith("child_stream.")) return null;
+  const stream = type.slice("child_stream.".length);
+  return CONFIGURABLE_CHILD_STREAMS.includes(stream as ConfigurableChildStream)
+    ? stream as ConfigurableChildStream
+    : null;
+}
+
+export function cleanChildStream(value: unknown): ChildStream {
+  if (typeof value !== "string" || !CHILD_STREAMS.includes(value as ChildStream)) {
+    throw new ValidationError(`stream must be one of: ${CHILD_STREAMS.join(", ")}`);
+  }
+  return value as ChildStream;
+}
 
-export function installNotificationSubscriptionRule(): void {
-  setSubscriptionRules([subscriptionRule]);
+export function childStreamSubscribed(input: {
+  parentId: string;
+  child: Pick<AgentCard, "id" | "teamId">;
+  stream: ChildStream;
+}): boolean {
+  if (input.stream === "responses") return true;
+  const parentId = cleanAgentId(input.parentId);
+  const type = childStreamSubscriptionType(input.stream);
+  const scope: NotificationScope = {
+    parent: parentId,
+    agentId: input.child.id,
+    ...(input.child.teamId ? { teamId: input.child.teamId } : {}),
+  };
+  const rows = getDb().query(`
+    SELECT * FROM notification_subscriptions
+    WHERE agent_id = ? AND type = ?
+    ORDER BY created_at ASC, id ASC
+  `).all(parentId, type) as NotificationSubscriptionRow[];
+
+  let subscribed = false;
+  for (const row of rows) {
+    const subscription = rowToSubscription(row);
+    if (!scopeMatches(subscription.scopeMatch, scope)) continue;
+    subscribed = subscription.mode === "opt_in";
+  }
+  return subscribed;
 }
 
 function getSubscription(id: string): NotificationSubscription | null {

package/src/index.ts

@@ -10,7 +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 { installNotificationSubscriptionRule } from "./notification-subscription-rules";
 import { startPlanLiveBindings } from "./services/plan-live-bindings";
 import { resolve, sep } from "path";
 import { gzipSync, brotliCompressSync, constants as zlibConstants } from "node:zlib";

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

@@ -1,23 +1,29 @@
 import {
   addSubscription,
+  childStreamFromSubscriptionType,
+  childStreamSubscriptionType,
+  cleanChildStream,
   cleanSubscriptionMode,
   cleanSubscriptionType,
+  CHILD_STREAMS,
   listSubscriptions,
   NOTIFICATION_SUBSCRIPTION_MODES,
   NOTIFICATION_SUBSCRIPTION_TYPES,
   removeSubscription,
+  type ConfigurableChildStream,
+  type ChildStream,
   type NotificationSubscriptionMode,
 } from "./db/notification-subscriptions";
 import { ValidationError } from "./db";
 import { McpAuthError } from "./mcp-errors";
 import { authContextFromMcp } from "./services/auth-context";
 import { cleanString } from "./validation";
-import type { NotificationScope } from "./notification-router";
+import type { NotificationScope } from "./notification-types";
 
 export const NOTIFICATION_SUBSCRIPTION_TOOLS = [
   {
     name: "relay_subscribe",
-    description: "Subscribe, opt out, or mute this caller agent for a notification type. The caller's token identity is the subscription owner.",
+    description: "Subscribe, opt out, or mute this caller agent for a notification type, or opt into child streams. Child response streams are always on; toolCalls/reasoning/narrative are opt-in.",
     requiredScopes: ["notifications:write"],
     inputSchema: {
       type: "object",
@@ -25,8 +31,11 @@ export const NOTIFICATION_SUBSCRIPTION_TOOLS = [
         type: { type: "string", enum: NOTIFICATION_SUBSCRIPTION_TYPES },
         mode: { type: "string", enum: NOTIFICATION_SUBSCRIPTION_MODES, description: "Default opt_in. mute and opt_out suppress matching default deliveries." },
         scope: { type: "object", description: "Optional partial notification scope match, such as { teamId } or { repoRoot }." },
+        streams: { type: "array", items: { type: "string", enum: CHILD_STREAMS }, description: "Child streams to opt into. responses is always on and is not persisted." },
+        childAgentId: { type: "string", description: "Limit child stream subscriptions to one spawned child." },
+        teamId: { type: "string", description: "Limit child stream subscriptions to children on a team." },
+        allChildren: { type: "boolean", description: "Subscribe for all children spawned by this caller. This is the default when childAgentId/teamId are omitted." },
       },
-      required: ["type"],
       additionalProperties: false,
     },
   },
@@ -41,6 +50,10 @@ export const NOTIFICATION_SUBSCRIPTION_TOOLS = [
         type: { type: "string", enum: NOTIFICATION_SUBSCRIPTION_TYPES },
         mode: { type: "string", enum: NOTIFICATION_SUBSCRIPTION_MODES },
         scope: { type: "object" },
+        streams: { type: "array", items: { type: "string", enum: CHILD_STREAMS } },
+        childAgentId: { type: "string" },
+        teamId: { type: "string" },
+        allChildren: { type: "boolean" },
       },
       additionalProperties: false,
     },
@@ -66,6 +79,27 @@ export function relayNotificationSubscriptionTool(
 ): Record<string, unknown> {
   const agentId = callerAgentId(auth);
   if (name === "relay_subscribe") {
+    if (Object.prototype.hasOwnProperty.call(args, "streams")) {
+      const scope = cleanChildStreamScope(args, agentId);
+      const streams = cleanChildStreams(args.streams);
+      const subscriptions = streams
+        .filter((stream): stream is ConfigurableChildStream => stream !== "responses")
+        .map((stream) => addSubscription({
+          agentId,
+          type: childStreamSubscriptionType(stream),
+          mode: cleanModeOrDefault(args.mode),
+          scopeMatch: scope,
+        }));
+      return {
+        subscriptions,
+        childStreamFilter: {
+          scope,
+          active: ["responses", ...streams.filter((stream) => stream !== "responses")],
+          responsesAlwaysOn: true,
+        },
+      };
+    }
+    if (args.type === undefined || args.type === null) throw new ValidationError("type or streams required");
     const subscription = addSubscription({
       agentId,
       type: cleanSubscriptionType(args.type),
@@ -76,6 +110,21 @@ export function relayNotificationSubscriptionTool(
   }
   if (name === "relay_unsubscribe") {
     const id = cleanString(args.id, "id", { max: 120 });
+    if (Object.prototype.hasOwnProperty.call(args, "streams")) {
+      const scope = cleanChildStreamScope(args, agentId);
+      const streams = cleanChildStreams(args.streams);
+      let removed = 0;
+      for (const stream of streams) {
+        if (stream === "responses") continue;
+        removed += removeSubscription({
+          agentId,
+          type: childStreamSubscriptionType(stream),
+          mode: args.mode === undefined || args.mode === null ? undefined : cleanSubscriptionMode(args.mode),
+          scopeMatch: scope,
+        });
+      }
+      return { removed, responsesAlwaysOn: true };
+    }
     const type = args.type === undefined || args.type === null ? undefined : cleanSubscriptionType(args.type);
     if (!id && !type) throw new ValidationError("id or type required");
     const removed = removeSubscription({
@@ -88,7 +137,17 @@ export function relayNotificationSubscriptionTool(
     return { removed };
   }
   if (name === "relay_list_subscriptions") {
-    return { subscriptions: listSubscriptions(agentId) };
+    const subscriptions = listSubscriptions(agentId);
+    return {
+      subscriptions,
+      childStreamFilter: {
+        default: ["responses"],
+        responsesAlwaysOn: true,
+        subscriptions: subscriptions
+          .map((subscription) => ({ ...subscription, stream: childStreamFromSubscriptionType(subscription.type) }))
+          .filter((subscription) => subscription.stream !== null),
+      },
+    };
   }
   throw new ValidationError(`unknown tool: ${name}`);
 }
@@ -109,3 +168,30 @@ function cleanScope(value: unknown): Partial<NotificationScope> | null {
   if (typeof value !== "object" || Array.isArray(value)) throw new ValidationError("scope must be an object");
   return value as Partial<NotificationScope>;
 }
+
+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))];
+}
+
+function cleanChildStreamScope(args: Record<string, unknown>, parentId: string): Partial<NotificationScope> {
+  const childAgentId = cleanString(args.childAgentId, "childAgentId", { max: 160 });
+  const teamId = cleanString(args.teamId, "teamId", { max: 160 });
+  if (childAgentId && teamId) throw new ValidationError("childAgentId and teamId are mutually exclusive");
+  const allChildren = args.allChildren === undefined || args.allChildren === null ? false : args.allChildren === true;
+  if (args.allChildren !== undefined && args.allChildren !== null && typeof args.allChildren !== "boolean") {
+    throw new ValidationError("allChildren must be a boolean");
+  }
+  if (allChildren && (childAgentId || teamId)) throw new ValidationError("allChildren cannot be combined with childAgentId or teamId");
+  const explicitScope = cleanScope(args.scope);
+  if (explicitScope) {
+    if (explicitScope.parent && explicitScope.parent !== parentId) throw new ValidationError("child stream scope.parent must match the caller");
+    if (childAgentId || teamId || allChildren) throw new ValidationError("scope cannot be combined with childAgentId, teamId, or allChildren");
+    return { ...explicitScope, parent: parentId };
+  }
+  return {
+    parent: parentId,
+    ...(childAgentId ? { agentId: childAgentId } : {}),
+    ...(teamId ? { teamId } : {}),
+  };
+}

package/src/memory-service.ts

@@ -5,6 +5,7 @@ import { assembleContextPackage, contextBudgetForAgent, estimateMemoryTokens } f
 import { createMemoryBrokerRegistry, memoryBrokerConfigFromEnv } from "./memory-broker-registry";
 import { filterMemoriesForInjection, formatUntrustedMemoryBlock } from "./memory-broker-contract";
 import { assertMemoryCreateAllowed } from "./memory-security";
+import { emitRelayInjectionEvent } from "./sse";
 import { basename } from "node:path";
 import type {
   ActiveMemoryClearReason,
@@ -88,6 +89,19 @@ export async function injectMemoryContext(input: MemoryInjectionInput): Promise<
       package: pkg,
     },
   });
+  emitRelayInjectionEvent({
+    agentId: input.agent.id,
+    category: "memory",
+    summary: `injected ${loadedMemoryIds.length} memor${loadedMemoryIds.length === 1 ? "y" : "ies"}: ${input.reason}`,
+    detail: {
+      source: input.source ?? "system",
+      reason: input.reason,
+      memoryIds: loadedMemoryIds,
+      content: formatUntrustedMemoryBlock(pkg, { generatedAt: input.ctx.now }),
+      package: pkg,
+    },
+    timestamp: input.ctx.now,
+  });
   return { command, package: pkg };
 }
 

package/src/notification-router.ts

@@ -1,5 +1,14 @@
 import { notifySystemMessage } from "./notify";
 import type { Message, MessageKind } from "./types";
+import { DEFAULT_TTL_MS } from "./notification-types";
+import type { NotificationScope, NotificationType } from "./notification-types";
+
+export {
+  DEFAULT_TTL_MS,
+  INFORMATIONAL_TTL_MS,
+  type NotificationScope,
+  type NotificationType,
+} from "./notification-types";
 
 /**
  * #440 — the single seam every agent-facing "wake" notification flows through. Before this,
@@ -16,48 +25,6 @@ import type { Message, MessageKind } from "./types";
  * `scope` (the entities a notification is ABOUT) is captured now even though #441 doesn't route on
  * it, so emitters are converted exactly once and the rule engine has its inputs the day it lands.
  */
-export type NotificationType =
-  | "landed-failure"
-  | "branch.landed"
-  | "agent.ready"
-  | "agent.exited"
-  | "agent.spawn_failed"
-  | "agent.context_threshold"
-  | "agent.resume_budget_exhausted"
-  | "agent.transient_land_hold"
-  | "agent.rate_limit_resume"
-  | "plan.bound_agent_exited"
-  | "workspace.steward_task"
-  | "workspace.conflict"
-  | "workspace.steward_reassigned"
-  | "workspace.stranded_escalation"
-  | "workspace.auto_abandoned"
-  | "workspace.review_request"
-  | "workspace.review_changes_requested";
-
-/**
- * The entities a notification is ABOUT — the future routing inputs (#442) and the explainability
- * subject (#446). All optional: each emitter fills the fields it has in scope at the call site.
- */
-export interface NotificationScope {
-  /** The agent whose work the notification concerns (branch author, workspace owner). */
-  author?: string;
-  /** The agent the notification is primarily about (lifecycle subject, advisory target). */
-  agentId?: string;
-  /** The spawn-parent that should hear about a child's lifecycle. */
-  parent?: string;
-  /** Team the notification belongs to (plan/coordination scope). */
-  teamId?: string;
-  /** Plan the notification concerns. */
-  planId?: string;
-  /** Repo checkout the notification concerns. */
-  repoRoot?: string;
-  /** Workspace the notification concerns. */
-  workspaceId?: string;
-  /** Files the notification concerns (path-scoped routing, #442). */
-  paths?: string[];
-}
-
 interface NotificationMessage {
   subject?: string;
   body: string;
@@ -89,39 +56,6 @@ interface RouteNotificationInput {
   emittedAt?: number;
 }
 
-const MINUTES = 60 * 1000;
-
-/**
- * Per-type default TTL (#451). Default-SAFE: anything about the recipient's own work or any
- * obligation is `null` (never auto-expires — store-ahead #234 must still deliver it). Only the
- * genuinely now-or-never pings get a short default; a stale one of those is actively misleading:
- *   - `agent.context_threshold` — the advisory band may have changed; old advice is wrong.
- *   - `agent.rate_limit_resume`  — "your hold cleared, resume" is pointless once the window moved.
- * Emitters opt INTO a shorter TTL per-call for the bystander/informational cases.
- */
-export const DEFAULT_TTL_MS: Record<NotificationType, number | null> = {
-  "landed-failure": null,
-  "branch.landed": null,
-  "agent.ready": null,
-  "agent.exited": null,
-  "agent.spawn_failed": null,
-  "agent.context_threshold": 15 * MINUTES,
-  "agent.resume_budget_exhausted": null,
-  "agent.transient_land_hold": null,
-  "agent.rate_limit_resume": 15 * MINUTES,
-  "plan.bound_agent_exited": null,
-  "workspace.steward_task": null,
-  "workspace.conflict": null,
-  "workspace.steward_reassigned": null,
-  "workspace.stranded_escalation": null,
-  "workspace.auto_abandoned": null,
-  "workspace.review_request": null,
-  "workspace.review_changes_requested": null,
-};
-
-/** Convenience TTL for emitter-supplied overrides on bystander/informational notifications. */
-export const INFORMATIONAL_TTL_MS = 30 * MINUTES;
-
 /**
  * Resolve the effective TTL: an explicit per-call `ttlMs` wins (including an explicit `null` =
  * never); `undefined` falls back to the per-type default.

package/src/notification-rules.ts

@@ -1,7 +1,7 @@
 import type { AgentCard } from "./types";
 import { listAgents } from "./db";
 import { isAgentOnline } from "./agent-ref";
-import type { NotificationType, NotificationScope } from "./notification-router";
+import type { NotificationType, NotificationScope } from "./notification-types";
 
 /**
  * #442 — the declarative rule engine that computes a notification's recipients FROM its `scope`,
@@ -18,9 +18,9 @@ import type { NotificationType, NotificationScope } from "./notification-router"
  * #441 explicit-recipients path. Nothing here is wired into production delivery yet — #444 does that.
  */
 
-export type RuleDecision = "deliver" | "suppress" | "abstain";
+type RuleDecision = "deliver" | "suppress" | "abstain";
 
-export interface NotificationRuleContext {
+interface NotificationRuleContext {
   type: NotificationType;
   scope: NotificationScope;
   /** Evaluation clock — passed in (never read via Date.now() inside a rule) so eval is testable. */

package/src/notification-subscription-rules.ts

@@ -0,0 +1,11 @@
+import { subscriptionDecisionFor } from "./db/notification-subscriptions";
+import { setSubscriptionRules, type NotificationRule } from "./notification-rules";
+
+const subscriptionRule: NotificationRule = {
+  name: "subscription:store",
+  evaluate: subscriptionDecisionFor,
+};
+
+export function installNotificationSubscriptionRule(): void {
+  setSubscriptionRules([subscriptionRule]);
+}

package/src/notification-types.ts

@@ -0,0 +1,70 @@
+export type NotificationType =
+  | "landed-failure"
+  | "branch.landed"
+  | "agent.ready"
+  | "agent.exited"
+  | "agent.spawn_failed"
+  | "agent.context_threshold"
+  | "agent.resume_budget_exhausted"
+  | "agent.transient_land_hold"
+  | "agent.rate_limit_resume"
+  | "plan.bound_agent_exited"
+  | "workspace.steward_task"
+  | "workspace.conflict"
+  | "workspace.steward_reassigned"
+  | "workspace.stranded_escalation"
+  | "workspace.auto_abandoned"
+  | "workspace.review_request"
+  | "workspace.review_changes_requested";
+
+/**
+ * The entities a notification is ABOUT: routing inputs (#442) and explainability subjects (#446).
+ * All optional because each emitter fills the fields it has in scope at the call site.
+ */
+export interface NotificationScope {
+  /** The agent whose work the notification concerns (branch author, workspace owner). */
+  author?: string;
+  /** The agent the notification is primarily about (lifecycle subject, advisory target). */
+  agentId?: string;
+  /** The spawn-parent that should hear about a child's lifecycle. */
+  parent?: string;
+  /** Team the notification belongs to (plan/coordination scope). */
+  teamId?: string;
+  /** Plan the notification concerns. */
+  planId?: string;
+  /** Repo checkout the notification concerns. */
+  repoRoot?: string;
+  /** Workspace the notification concerns. */
+  workspaceId?: string;
+  /** Files the notification concerns (path-scoped routing, #442). */
+  paths?: string[];
+}
+
+const MINUTES = 60 * 1000;
+
+/**
+ * Per-type default TTL (#451). Default-SAFE: anything about the recipient's own work or any
+ * obligation is `null` (never auto-expires). Only genuinely now-or-never pings get a short default.
+ */
+export const DEFAULT_TTL_MS: Record<NotificationType, number | null> = {
+  "landed-failure": null,
+  "branch.landed": null,
+  "agent.ready": null,
+  "agent.exited": null,
+  "agent.spawn_failed": null,
+  "agent.context_threshold": 15 * MINUTES,
+  "agent.resume_budget_exhausted": null,
+  "agent.transient_land_hold": null,
+  "agent.rate_limit_resume": 15 * MINUTES,
+  "plan.bound_agent_exited": null,
+  "workspace.steward_task": null,
+  "workspace.conflict": null,
+  "workspace.steward_reassigned": null,
+  "workspace.stranded_escalation": null,
+  "workspace.auto_abandoned": null,
+  "workspace.review_request": null,
+  "workspace.review_changes_requested": null,
+};
+
+/** Convenience TTL for emitter-supplied overrides on bystander/informational notifications. */
+export const INFORMATIONAL_TTL_MS = 30 * MINUTES;