agent-relay-server 0.59.0 → 0.60.1

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();

package/src/maintenance.ts

@@ -13,6 +13,7 @@ import {
   expireQueuedMessages,
   getAgent,
   getDb,
+  getActiveMergePause,
   getRepoSteward,
   getWorkspace,
   listActiveTeams,
@@ -59,11 +60,12 @@ import {
   emitPoolBindingChanged,
   emitTaskChanged,
 } from "./sse";
-import { notifySystemMessage } from "./notify";
+import { routeNotification, type NotificationType, type NotificationScope } from "./notification-router";
 import { pruneExpiredTokenRecords } from "./token-db";
 import { dissolveTeamById } from "./services/team";
 import { reapTransientAgents, resetTransientTrackerForTests } from "./services/transient-agent-reaper";
 import { resumeRateLimitedAgents, resetRateLimitResumeTrackerForTests } from "./services/rate-limit-resume";
+import { MERGE_PAUSE_MAINTENANCE_JOB } from "./merge-pause-maintenance";
 import type { Command, MaintenanceJob, MaintenanceJobRun } from "./types";
 
 const DEFAULT_TIMEOUT_MS = 30_000;
@@ -197,6 +199,7 @@ const definitions: MaintenanceJobDefinition[] = [
       };
     },
   },
+  MERGE_PAUSE_MAINTENANCE_JOB,
   {
     id: "task-orphan-release",
     title: "Orphaned task release",
@@ -633,10 +636,16 @@ function wakeRepoSteward(ws: WorkspaceRecord, reason: string): string | null {
   const policyName = ensureRepoSteward(ws.repoRoot);
   if (!policyName) return null;
   try {
-    notifySystemMessage(`policy:${policyName}`, {
-      subject: `Steward: ${ws.status} workspace needs attention`,
-      body: `Workspace \`${ws.branch ?? ws.id}\` (id ${ws.id}) in ${ws.repoRoot} is ${ws.status} and could not auto-land (${reason}). Claim it first so auto-merge yields: \`agent-relay workspace claim --id ${ws.id} --purpose steward\`. Inspect: \`agent-relay steward inspect ${ws.id}\`. Then cd into ${ws.worktreePath}, rebase onto ${ws.baseRef ?? "base"}, resolve, run checks, and land: \`agent-relay workspace land --id ${ws.id} --strategy rebase-ff\` — or \`agent-relay workspace release --id ${ws.id}\` and escalate if you can't.`,
-      payload: { kind: "workspace.steward-task", workspaceId: ws.id, repoRoot: ws.repoRoot, worktreePath: ws.worktreePath, branch: ws.branch, baseRef: ws.baseRef, status: ws.status, reason },
+    // Obligation (ttl null by type default): a steward task must survive until claimed/handled.
+    routeNotification({
+      type: "workspace.steward_task",
+      scope: { workspaceId: ws.id, repoRoot: ws.repoRoot },
+      recipients: [`policy:${policyName}`],
+      message: {
+        subject: `Steward: ${ws.status} workspace needs attention`,
+        body: `Workspace \`${ws.branch ?? ws.id}\` (id ${ws.id}) in ${ws.repoRoot} is ${ws.status} and could not auto-land (${reason}). Claim it first so auto-merge yields: \`agent-relay workspace claim --id ${ws.id} --purpose steward\`. Inspect: \`agent-relay steward inspect ${ws.id}\`. Then cd into ${ws.worktreePath}, rebase onto ${ws.baseRef ?? "base"}, resolve, run checks, and land: \`agent-relay workspace land --id ${ws.id} --strategy rebase-ff\` — or \`agent-relay workspace release --id ${ws.id}\` and escalate if you can't.`,
+        payload: { kind: "workspace.steward-task", workspaceId: ws.id, repoRoot: ws.repoRoot, worktreePath: ws.worktreePath, branch: ws.branch, baseRef: ws.baseRef, status: ws.status, reason },
+      },
     });
     getLifecycleManager().onMessageForPolicy(policyName);
     patchWorkspaceMetadata(ws.id, { stewardWokenAt: Date.now(), stewardPolicy: policyName });
@@ -653,9 +662,8 @@ async function scanWorkspaceConflicts(): Promise<Record<string, unknown>> {
   const candidates = listWorkspaces().filter(
     (ws) => ws.mode === "isolated" && Boolean(ws.worktreePath) && CONFLICT_SCAN_STATUSES.has(ws.status),
   );
-  const flagged: string[] = [], cleared: string[] = [], merged: string[] = [], notifiedStewards: string[] = [];
+  const flagged: string[] = [], cleared: string[] = [], merged: string[] = [], notifiedStewards: string[] = [], prRecycled: string[] = [];
   const reviewerArmed: string[] = [], reviewerChangesRequested: string[] = [], relayPrMerged: string[] = [], relayPrWaiting: string[] = [];
-  const prRecycled: string[] = [];
 
   for (const ws of candidates) {
     const orch = orchestrators.find((candidate) => workspacePathWithinBase(ws.sourceCwd, candidate.baseDir));
@@ -702,6 +710,7 @@ async function scanWorkspaceConflicts(): Promise<Record<string, unknown>> {
     const prAction = preparePrCompletionScan(ws, p, orch.agentId);
     if (prAction.armCommand) { emitCommand(prAction.armCommand); reviewerArmed.push(ws.id); continue; }
     if (prAction.notifiedOwner) { reviewerChangesRequested.push(ws.id); continue; }
+    if (prAction.refreshCommand) { emitCommand(prAction.refreshCommand); continue; }
     if (prAction.mergeCommand) { emitCommand(prAction.mergeCommand); relayPrMerged.push(ws.id); continue; }
     if (prAction.waitReason) relayPrWaiting.push(`${ws.id}:${prAction.waitReason}`);
     if (prAction.stop) continue;
@@ -740,10 +749,16 @@ async function scanWorkspaceConflicts(): Promise<Record<string, unknown>> {
         if (woke) notifiedStewards.push(woke);
       } else if (ws.stewardAgentId) {
         try {
-          notifySystemMessage(ws.stewardAgentId, {
-            subject: "Workspace merge conflict",
-            body: `Workspace \`${ws.branch ?? ws.id}\` in ${ws.repoRoot} can no longer merge cleanly into ${p.baseRef ?? "base"} (${p.ahead ?? "?"} ahead, ${p.behind ?? "?"} behind). As repo steward, please coordinate resolution.`,
-            payload: { kind: "workspace.conflict", workspaceId: ws.id, repoRoot: ws.repoRoot, branch: ws.branch, baseRef: p.baseRef, ahead: p.ahead, behind: p.behind },
+          // Obligation (ttl null by type default): a conflict handoff must reach the steward.
+          routeNotification({
+            type: "workspace.conflict",
+            scope: { workspaceId: ws.id, repoRoot: ws.repoRoot },
+            recipients: [ws.stewardAgentId],
+            message: {
+              subject: "Workspace merge conflict",
+              body: `Workspace \`${ws.branch ?? ws.id}\` in ${ws.repoRoot} can no longer merge cleanly into ${p.baseRef ?? "base"} (${p.ahead ?? "?"} ahead, ${p.behind ?? "?"} behind). As repo steward, please coordinate resolution.`,
+              payload: { kind: "workspace.conflict", workspaceId: ws.id, repoRoot: ws.repoRoot, branch: ws.branch, baseRef: p.baseRef, ahead: p.ahead, behind: p.behind },
+            },
           });
           notifiedStewards.push(ws.stewardAgentId);
         } catch {
@@ -774,16 +789,13 @@ async function autoMergeCleanFastForwards(): Promise<Record<string, unknown>> {
   );
   const stewardEnabled = getStewardConfig().enabled;
   const merged: string[] = [];
-  const heldByLease: string[] = [];
-  const heldByClaim: string[] = [];
-  const heldAwaitingApproval: string[] = [];
-  const leftForSteward: string[] = [];
-  const wokeStewards: string[] = [];
+  const heldByLease: string[] = [], heldByClaim: string[] = [], heldByPause: string[] = [], heldAwaitingApproval: string[] = [], leftForSteward: string[] = [], wokeStewards: string[] = [];
 
   for (const ws of candidates) {
     if (isAwaitingReviewerApproval(ws)) { heldAwaitingApproval.push(ws.id); continue; }
     // A claimed workspace is being validated by a steward — don't race it (#208).
     if (workspaceActiveClaim(ws)) { heldByClaim.push(ws.id); continue; }
+    if (getActiveMergePause(ws.repoRoot, ws.baseRef ?? "main")) { heldByPause.push(ws.id); continue; }
     const orch = orchestrators.find((candidate) => workspacePathWithinBase(ws.sourceCwd, candidate.baseDir));
     if (!orch?.apiUrl) continue;
     const preview = await fetchHostMergePreview(orch.apiUrl, ws);
@@ -845,15 +857,16 @@ async function autoMergeCleanFastForwards(): Promise<Record<string, unknown>> {
     });
   }
 
-  return { scanned: candidates.length, merged, heldByLease, heldByClaim, heldAwaitingApproval, leftForSteward, wokeStewards };
+  return { scanned: candidates.length, merged, heldByLease, heldByClaim, heldByPause, heldAwaitingApproval, leftForSteward, wokeStewards };
 }
 
-// Send a system DM, swallowing failures (a stale/missing/misconfigured target
-// must never break the GC sweep). Returns the target on success, null otherwise.
-function notifyTarget(target: string, subject: string, body: string, payload: Record<string, unknown>): string | null {
+// Route a GC notification, swallowing failures (a stale/missing/misconfigured target must never
+// break the GC sweep). Returns the target on success, null otherwise. These are all obligation-style
+// workspace handoffs (null TTL by type default) — they must survive until the recipient acts.
+function notifyTarget(type: NotificationType, scope: NotificationScope, target: string, subject: string, body: string, payload: Record<string, unknown>): string | null {
   if (!target) return null;
   try {
-    notifySystemMessage(target, { subject, body, payload });
+    routeNotification({ type, scope, recipients: [target], message: { subject, body, payload } });
     return target;
   } catch {
     return null;
@@ -905,6 +918,8 @@ async function workspaceGC(): Promise<Record<string, unknown>> {
       // steward hasn't been told, hand it off explicitly, then clear markers.
       if (strandedAt !== undefined && meta.strandedNotifiedSteward !== steward) {
         const sent = notifyTarget(
+          "workspace.steward_reassigned",
+          { workspaceId: fresh.id, repoRoot: fresh.repoRoot },
           steward!,
           "Workspace stewardship reassigned",
           `You are now steward for ${fresh.repoRoot}. Workspace \`${fresh.branch ?? fresh.id}\` is ${fresh.status} and was stranded without an online steward — please coordinate ${fresh.status === "conflict" ? "conflict resolution" : "review/merge"}.`,
@@ -920,6 +935,8 @@ async function workspaceGC(): Promise<Record<string, unknown>> {
     if (strandedAt === undefined) { patchWorkspaceMetadata(fresh.id, { strandedAt: now }); continue; }
     if (now - strandedAt < escalationMs || meta.escalatedAt) continue;
     const sent = notifyTarget(
+      "workspace.stranded_escalation",
+      { workspaceId: fresh.id, repoRoot: fresh.repoRoot },
       fallbackTarget,
       "Stranded workspace needs an owner",
       `Workspace \`${fresh.branch ?? fresh.id}\` in ${fresh.repoRoot} is ${fresh.status} with no online steward (all repo agents offline) for ${Math.round((now - strandedAt) / (60 * 60 * 1000))}h. Please coordinate ${fresh.status === "conflict" ? "conflict resolution" : "review/merge"} or clean up the worktree.`,
@@ -951,6 +968,8 @@ async function workspaceGC(): Promise<Record<string, unknown>> {
       // stranded abandon isn't silent (issue #157).
       const target = ws.stewardAgentId ?? fallbackTarget;
       const sent = notifyTarget(
+        "workspace.auto_abandoned",
+        { workspaceId: ws.id, repoRoot: ws.repoRoot },
         target,
         "Workspace auto-abandoned",
         `Workspace \`${ws.branch ?? ws.id}\` in ${ws.repoRoot} was auto-abandoned after ${Math.round(WORKSPACE_REVIEW_TTL_MS / DAY_MS)}d without steward action. Run workspace cleanup to reclaim the worktree.`,

package/src/mcp-merge-tools.ts

@@ -0,0 +1,66 @@
+import { ValidationError } from "./db";
+import { McpNotFoundError } from "./mcp-errors";
+import { authContextFromMcp } from "./services/auth-context";
+import { listAutoMergePauses, pauseAutoMerge, renewAutoMergePause, resumeAutoMerge } from "./services/merge-pause";
+import { cleanString } from "./validation";
+
+export const MERGE_TOOLS = [
+  { name: "relay_merge_pauses", description: "List active auto-merge pauses. These are repo/base-level holds that make the workspace auto-merge job yield during release or build critical sections.", requiredScopes: ["command:read"], inputSchema: { type: "object", properties: {}, additionalProperties: false } },
+  {
+    name: "relay_merge_pause",
+    description: "Pause workspace auto-merge for one repo/base pair with a TTL. Existing active pause for the same target is returned as a conflict instead of replacing its holder.",
+    requiredScopes: ["command:write"],
+    inputSchema: {
+      type: "object",
+      properties: {
+        repoRoot: { type: "string", description: "Repository root whose auto-merge should pause." },
+        baseRef: { type: "string", description: "Base branch/ref to pause (default main)." },
+        ttlMs: { type: "integer", minimum: 1, description: "Pause TTL in milliseconds. Defaults to the server's merge-pause TTL." },
+        reason: { type: "string" },
+        holder: { type: "string", description: "Optional human-readable holder. Defaults to the authenticated caller." },
+      },
+      required: ["repoRoot"],
+      additionalProperties: false,
+    },
+  },
+  { name: "relay_merge_renew", description: "Renew an active auto-merge pause by id, extending its TTL from now.", requiredScopes: ["command:write"], inputSchema: { type: "object", properties: { id: { type: "string" }, ttlMs: { type: "integer", minimum: 1 } }, required: ["id"], additionalProperties: false } },
+  { name: "relay_merge_resume", description: "Release an auto-merge pause by id, or by repoRoot/baseRef.", requiredScopes: ["command:write"], inputSchema: { type: "object", properties: { id: { type: "string" }, repoRoot: { type: "string" }, baseRef: { type: "string", description: "Base branch/ref (default main when repoRoot is used)." } }, additionalProperties: false } },
+] satisfies Array<{ name: string; description: string; requiredScopes: string[]; inputSchema: Record<string, unknown> }>;
+
+type McpAuthLike = Parameters<typeof authContextFromMcp>[0];
+
+export function relayMergeTool(auth: McpAuthLike, name: string, args: Record<string, unknown>): Record<string, unknown> {
+  const ctx = authContextFromMcp(auth);
+  if (name === "relay_merge_pauses") {
+    const pauses = listAutoMergePauses();
+    return { pauses, count: pauses.length };
+  }
+  if (name === "relay_merge_pause") {
+    const result = pauseAutoMerge({
+      repoRoot: cleanString(args.repoRoot, "repoRoot", { required: true, max: 1024 })!,
+      baseRef: cleanString(args.baseRef, "baseRef", { max: 240 }),
+      holder: cleanString(args.holder, "holder", { max: 240 }) ?? ctx.callerAgentId ?? ctx.actor.id,
+      reason: cleanString(args.reason, "reason", { max: 1000 }),
+      ttlMs: optionalPositiveInt(args.ttlMs, "ttlMs"),
+    });
+    return result.ok ? { ok: true, pause: result.pause } : { ok: false, error: "merge target already paused", pause: result.pause };
+  }
+  if (name === "relay_merge_renew") {
+    const pause = renewAutoMergePause(cleanString(args.id, "id", { required: true, max: 120 })!, optionalPositiveInt(args.ttlMs, "ttlMs"));
+    if (!pause) throw new McpNotFoundError("merge pause not found or expired");
+    return { pause };
+  }
+  if (name === "relay_merge_resume") {
+    const id = cleanString(args.id, "id", { max: 120 });
+    const repoRoot = cleanString(args.repoRoot, "repoRoot", { max: 1024 });
+    if (!id && !repoRoot) throw new ValidationError("id or repoRoot required");
+    return { released: resumeAutoMerge({ id, repoRoot, baseRef: cleanString(args.baseRef, "baseRef", { max: 240 }) }) };
+  }
+  throw new ValidationError(`unknown tool: ${name}`);
+}
+
+function optionalPositiveInt(value: unknown, field: string): number | undefined {
+  if (value === undefined || value === null) return undefined;
+  if (typeof value !== "number" || !Number.isSafeInteger(value) || value <= 0) throw new ValidationError(`${field} must be a positive integer`);
+  return value;
+}

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

@@ -0,0 +1,111 @@
+import {
+  addSubscription,
+  cleanSubscriptionMode,
+  cleanSubscriptionType,
+  listSubscriptions,
+  NOTIFICATION_SUBSCRIPTION_MODES,
+  NOTIFICATION_SUBSCRIPTION_TYPES,
+  removeSubscription,
+  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";
+
+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.",
+    requiredScopes: ["notifications:write"],
+    inputSchema: {
+      type: "object",
+      properties: {
+        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 }." },
+      },
+      required: ["type"],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "relay_unsubscribe",
+    description: "Remove this caller agent's notification subscription by id, or by type/mode/scope. Omitting mode removes all modes for the matched type/scope.",
+    requiredScopes: ["notifications:write"],
+    inputSchema: {
+      type: "object",
+      properties: {
+        id: { type: "string" },
+        type: { type: "string", enum: NOTIFICATION_SUBSCRIPTION_TYPES },
+        mode: { type: "string", enum: NOTIFICATION_SUBSCRIPTION_MODES },
+        scope: { type: "object" },
+      },
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "relay_list_subscriptions",
+    description: "List this caller agent's durable notification subscriptions.",
+    requiredScopes: ["notifications:read"],
+    inputSchema: {
+      type: "object",
+      properties: {},
+      additionalProperties: false,
+    },
+  },
+] satisfies Array<{ name: string; description: string; requiredScopes: string[]; inputSchema: Record<string, unknown> }>;
+
+type McpAuthLike = Parameters<typeof authContextFromMcp>[0];
+
+export function relayNotificationSubscriptionTool(
+  auth: McpAuthLike,
+  name: string,
+  args: Record<string, unknown>,
+): Record<string, unknown> {
+  const agentId = callerAgentId(auth);
+  if (name === "relay_subscribe") {
+    const subscription = addSubscription({
+      agentId,
+      type: cleanSubscriptionType(args.type),
+      mode: cleanModeOrDefault(args.mode),
+      scopeMatch: cleanScope(args.scope),
+    });
+    return { subscription };
+  }
+  if (name === "relay_unsubscribe") {
+    const id = cleanString(args.id, "id", { max: 120 });
+    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({
+      agentId,
+      id,
+      type,
+      mode: args.mode === undefined || args.mode === null ? undefined : cleanSubscriptionMode(args.mode),
+      ...(Object.prototype.hasOwnProperty.call(args, "scope") ? { scopeMatch: cleanScope(args.scope) } : {}),
+    });
+    return { removed };
+  }
+  if (name === "relay_list_subscriptions") {
+    return { subscriptions: listSubscriptions(agentId) };
+  }
+  throw new ValidationError(`unknown tool: ${name}`);
+}
+
+function callerAgentId(auth: McpAuthLike): string {
+  const ctx = authContextFromMcp(auth);
+  if (!ctx.callerAgentId) throw new McpAuthError("notification subscriptions require a single caller agent identity");
+  return ctx.callerAgentId;
+}
+
+function cleanModeOrDefault(value: unknown): NotificationSubscriptionMode {
+  if (value === undefined || value === null) return "opt_in";
+  return cleanSubscriptionMode(value);
+}
+
+function cleanScope(value: unknown): Partial<NotificationScope> | null {
+  if (value === undefined || value === null) return null;
+  if (typeof value !== "object" || Array.isArray(value)) throw new ValidationError("scope must be an object");
+  return value as Partial<NotificationScope>;
+}

package/src/mcp.ts

@@ -50,6 +50,7 @@ import { PLAN_TOOLS, relayPlanTool } from "./mcp-plan-tools";
 import { TEAM_TOOLS, relayTeamTool } from "./mcp-team-tools";
 import { BLACKBOARD_TOOLS, relayBlackboardTool } from "./mcp-blackboard-tools";
 import { PROJECT_TOOLS, relayProjectTool } from "./mcp-project-tools";
+import { NOTIFICATION_SUBSCRIPTION_TOOLS, relayNotificationSubscriptionTool } from "./mcp-notification-subscription-tools"; import { MERGE_TOOLS, relayMergeTool } from "./mcp-merge-tools";
 import { PROJECT_INSTRUCTION_POLICY_NAMES, parseProjectInstructions } from "./project-instructions";
 import { AGENT_ACTION_TOOL, relayAgentAction } from "./mcp-agent-action";
 import type { ActivityKind, AgentLifecycle, ArtifactKind, ArtifactSensitivity, AttachmentRef, Command, SendMessageInput, Message, SpawnApprovalMode, SpawnProvider, WorkspaceAutoMergePolicy, WorkspaceMergeStrategy, WorkspaceMode, WorkspaceRecord } from "./types";
@@ -459,10 +460,11 @@ const TOOLS: ToolDefinition[] = [
       additionalProperties: false,
     },
   },
-  ...TEAM_TOOLS,
+  ...MERGE_TOOLS, ...TEAM_TOOLS,
   ...PLAN_TOOLS,
   ...BLACKBOARD_TOOLS,
   ...PROJECT_TOOLS,
+  ...NOTIFICATION_SUBSCRIPTION_TOOLS,
 ];
 
 export async function postMcp(req: Request): Promise<Response> {
@@ -575,10 +577,11 @@ async function callTool(auth: McpAuthContext, params: unknown): Promise<Record<s
     else if (name === "relay_workspace_claim") result = relayWorkspaceMutation(auth, "claim", args);
     else if (name === "relay_workspace_release") result = relayWorkspaceMutation(auth, "release-claim", args);
     else if (name === "relay_workspace_land") result = relayWorkspaceMutation(auth, "merge", args);
-    else if (name.startsWith("relay_team_")) result = await relayTeamTool(auth, name, args);
+    else if (name.startsWith("relay_merge_")) result = relayMergeTool(auth, name, args); else if (name.startsWith("relay_team_")) result = await relayTeamTool(auth, name, args);
     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 === "relay_subscribe" || name === "relay_unsubscribe" || name === "relay_list_subscriptions") result = relayNotificationSubscriptionTool(auth, name, args);
     else throw new ValidationError(`unknown tool: ${name}`);
 
     auditToolCall(auth, name, "ok", result);
@@ -1040,7 +1043,6 @@ function relayWorkspaceMutation(auth: McpAuthContext, action: WorkspaceAction, a
   return payload;
 }
 
-
 function payloadWithAttachments(
   payload: Record<string, unknown> | undefined,
   attachments: AttachmentRef[] | undefined,

package/src/merge-pause-maintenance.ts

@@ -0,0 +1,13 @@
+import { REAP_INTERVAL_MS } from "./config";
+import { releaseExpiredMergePauses } from "./db";
+
+export const MERGE_PAUSE_MAINTENANCE_JOB = {
+  id: "merge-pause-expiration",
+  title: "Merge pause expiration",
+  description: "Release expired repo/base auto-merge pauses.",
+  intervalMs: REAP_INTERVAL_MS,
+  runOnStart: true,
+  handler() {
+    return { releasedMergePauseIds: releaseExpiredMergePauses() };
+  },
+};