agent-relay-server 0.91.4 → 0.93.0

package/src/db/workspaces.ts

@@ -74,10 +74,15 @@ import type {
   ProviderCapabilities,
   TaskStatusInput,
   WorkspaceMetadata,
+  WorkspaceAutoMergePolicy,
+  WorkspaceLandingPolicy,
   WorkspaceRecord,
   WorkspaceStatus,
 } from "../types";
 
+const SPAWN_LAND_STRATEGIES = ["direct", "pr"] as const;
+const SPAWN_AUTO_MERGE_POLICIES = ["on-green", "on-approval", "manual"] as const;
+
 function rowToWorkspace(row: any): WorkspaceRecord {
   return {
     id: row.id,
@@ -102,6 +107,36 @@ function rowToWorkspace(row: any): WorkspaceRecord {
   };
 }
 
+function workspaceLandMetadataFrom(value: Record<string, unknown> | undefined): {
+  landStrategy?: WorkspaceLandingPolicy;
+  autoMerge?: WorkspaceAutoMergePolicy;
+  reviewer?: string;
+} {
+  if (!value) return {};
+  const landStrategy = typeof value.landStrategy === "string" && (SPAWN_LAND_STRATEGIES as readonly string[]).includes(value.landStrategy)
+    ? value.landStrategy as WorkspaceLandingPolicy
+    : undefined;
+  const autoMerge = typeof value.autoMerge === "string" && (SPAWN_AUTO_MERGE_POLICIES as readonly string[]).includes(value.autoMerge)
+    ? value.autoMerge as WorkspaceAutoMergePolicy
+    : undefined;
+  const reviewer = typeof value.reviewer === "string" && value.reviewer.trim() ? value.reviewer.trim() : undefined;
+  return {
+    ...(landStrategy ? { landStrategy } : {}),
+    ...(autoMerge ? { autoMerge } : {}),
+    ...(reviewer ? { reviewer } : {}),
+  };
+}
+
+function spawnCommandLandMetadata(spawnRequestId: string | undefined): ReturnType<typeof workspaceLandMetadataFrom> {
+  if (!spawnRequestId) return {};
+  const row = getDb().query(`
+    SELECT params FROM commands
+    WHERE type = 'agent.spawn' AND correlation_id = ?
+    ORDER BY created_at DESC
+    LIMIT 1
+  `).get(spawnRequestId) as { params?: string } | undefined;
+  return workspaceLandMetadataFrom(parseJson<Record<string, unknown>>(row?.params, {}));
+}
 
 export function upsertWorkspaceFromManagedAgent(agent: ManagedAgent): WorkspaceRecord | null {
   const workspace = agent.workspace;
@@ -140,7 +175,15 @@ export function upsertWorkspaceFromManagedAgent(agent: ManagedAgent): WorkspaceR
       ownerAgentId: agent.agentId || undefined,
       ownerPolicyName: agent.policyName,
       ownerAutomationRunId: agent.automationRunId,
-      metadata: { ...(existing?.metadata ?? {}), provider: agent.provider, label: agent.label, sessionName: agent.sessionName, tmuxSession: agent.tmuxSession },
+      metadata: {
+        ...(existing?.metadata ?? {}),
+        ...spawnCommandLandMetadata(agent.spawnRequestId),
+        ...workspaceLandMetadataFrom(workspace as unknown as Record<string, unknown>),
+        provider: agent.provider,
+        label: agent.label,
+        sessionName: agent.sessionName,
+        tmuxSession: agent.tmuxSession,
+      },
     });
   }
   // Shared-mode occupancy: one row per agent sharing a git repo, with no
@@ -438,4 +481,3 @@ export function electWorkspaceStewardsForAgent(agentId: string): void {
   `).all(agentId) as Array<{ repo_root: string }>;
   for (const r of repos) electWorkspaceStewards(r.repo_root);
 }
-

package/src/maintenance/constants.ts

@@ -11,6 +11,7 @@ import {
   TOKEN_RECORD_RETENTION_SECONDS,
   WORKSPACE_AUTO_MERGE_INTERVAL_MS,
   WORKSPACE_GC_INTERVAL_MS,
+  WORKSPACE_IDLE_REFRESH_INTERVAL_MS,
   WORKSPACE_ORPHAN_REAPER_INTERVAL_MS,
   WORKSPACE_RETENTION_MS,
   WORKSPACE_REVIEW_TTL_MS,
@@ -45,6 +46,7 @@ export {
   TOKEN_RECORD_RETENTION_SECONDS,
   WORKSPACE_AUTO_MERGE_INTERVAL_MS,
   WORKSPACE_GC_INTERVAL_MS,
+  WORKSPACE_IDLE_REFRESH_INTERVAL_MS,
   WORKSPACE_ORPHAN_REAPER_INTERVAL_MS,
   WORKSPACE_RETENTION_MS,
   WORKSPACE_REVIEW_TTL_MS,

package/src/maintenance/jobs.ts

@@ -53,6 +53,7 @@ import {
   QUOTA_HISTORY_RETENTION_MS,
   TOKEN_RECORD_RETENTION_SECONDS,
   WORKSPACE_AUTO_MERGE_INTERVAL_MS,
+  WORKSPACE_IDLE_REFRESH_INTERVAL_MS,
   WORKSPACE_GC_INTERVAL_MS,
   WORKSPACE_ORPHAN_REAPER_INTERVAL_MS,
   CONFLICT_SCAN_INTERVAL_MS,
@@ -61,7 +62,7 @@ import {
 import { emitCommand } from "./events";
 import { reapOrphanedSessions } from "./orphaned-sessions";
 import { reapZeroMemberTeams, runTeamIdleWatchdog } from "./teams";
-import { scanWorkspaceConflicts, workspaceGC } from "./workspaces";
+import { refreshIdleWorkspaces, scanWorkspaceConflicts, workspaceGC } from "./workspaces";
 import type { MaintenanceJobDefinition } from "./types";
 
 let dbMaintenanceRuns = 0;
@@ -227,6 +228,14 @@ export const definitions: MaintenanceJobDefinition[] = [
     runOnStart: true,
     handler() {
       const expired = expireStaleBusAgents();
+      for (const id of expired.agentIds) {
+        getLifecycleManager().onAgentDisappeared(id);
+        // #636/#659 — only after the stale reconnect grace expires do we turn a bare
+        // heartbeat gap into a terminal parent notification. A live runner that
+        // reconnects before this point heals from `stale` without a false exit.
+        const diagnosis = diagnoseAgentDeath({ agent: getAgent(id), reason: "heartbeat lost" });
+        notifyAgentOffline(id, "heartbeat lost", diagnosis);
+      }
       for (const task of expired.orphanedTasks) emitTaskChanged(task, "task.updated");
       return {
         expiredBusAgentIds: expired.agentIds,
@@ -244,16 +253,11 @@ export const definitions: MaintenanceJobDefinition[] = [
       const reapedAgentIds = reapStaleAgents(STALE_TTL_MS);
       for (const id of reapedAgentIds) {
         emitAgentStatus(id);
-        getLifecycleManager().onAgentDisappeared(id);
-        // #636 — a heartbeat-lost death still gets a best-effort post-mortem from the agent's last
-        // known meta (lastExit/lastError/auth) + heartbeat gap, riding the terminal event.
-        const diagnosis = diagnoseAgentDeath({ agent: getAgent(id), reason: "heartbeat lost" });
-        notifyAgentOffline(id, "heartbeat lost", diagnosis);
         createActivityEvent({
           clientId: "server-agent-" + id + "-heartbeat-lost-" + Date.now(),
           kind: "state",
-          title: "Heartbeat lost",
-          body: "Agent marked offline",
+          title: "Heartbeat stale",
+          body: "Agent entered reconnect grace",
           meta: id,
           icon: "ti-heart-off",
           view: "chat",
@@ -442,6 +446,15 @@ export const definitions: MaintenanceJobDefinition[] = [
     timeoutMs: 60 * 1000,
     handler: autoMergeCleanFastForwards,
   },
+  {
+    id: "workspace-idle-refresh",
+    title: "Workspace idle refresh",
+    description: "Proactively advance idle branch-agent workspaces to origin/main (#478): for each active, clean (dirty=0, ahead=0), owner-idle workspace, dispatch a workspace.idle-refresh command so the agent wakes already current and needs no ready/status dance.",
+    intervalMs: WORKSPACE_IDLE_REFRESH_INTERVAL_MS,
+    runOnStart: false,
+    timeoutMs: 60 * 1000,
+    handler: refreshIdleWorkspaces,
+  },
   {
     id: "workspace-gc",
     title: "Workspace GC",

package/src/maintenance/workspaces.ts

@@ -11,6 +11,7 @@ import {
   reelectRepoSteward,
   releaseExpiredMergeLeases,
   updateWorkspaceStatus,
+  setWorkspaceBranch,
 } from "../db";
 import type { WorkspaceMergePreview, WorkspaceStatus } from "../types";
 import { notifyStewardHandoff, reconcileLandedWorkspace } from "../branch-landed";
@@ -262,3 +263,78 @@ export async function workspaceGC(): Promise<Record<string, unknown>> {
     escalationTargets,
   };
 }
+
+/**
+ * Proactively refresh idle branch-agent workspaces against origin/main (#478).
+ *
+ * For each `active` isolated workspace whose owner agent is NOT busy and whose
+ * stored probe data indicates no WIP (dirty=0, ahead=0), dispatch a
+ * `workspace.idle-refresh` command to the owning orchestrator. The orchestrator
+ * re-verifies liveness, fetches origin, and — when the worktree is cleanly
+ * behind — performs a `checkout -B <fresh> origin/main` so the agent is already
+ * current when it next wakes. Workspaces with WIP, commits ahead, or busy owners
+ * are skipped silently.
+ */
+export async function refreshIdleWorkspaces(): Promise<Record<string, unknown>> {
+  const orchestrators = listOrchestrators().filter((orch) => orch.status === "online" && orch.agentId);
+  if (!orchestrators.length) return { dispatched: 0, skipped: 0, reason: "no online orchestrators" };
+
+  const candidates = listWorkspaces().filter(
+    (ws) => ws.mode === "isolated" && ws.status === "active" && Boolean(ws.worktreePath),
+  );
+
+  const dispatched: string[] = [];
+  const skipped: string[] = [];
+  const now = Date.now();
+
+  for (const ws of candidates) {
+    const orch = orchestrators.find((candidate) => workspacePathWithinBase(ws.sourceCwd, candidate.baseDir));
+    if (!orch?.agentId) { skipped.push(`${ws.id}:no-orchestrator`); continue; }
+
+    // Gate: owner must exist and not be busy.
+    const owner = ws.ownerAgentId ? getAgent(ws.ownerAgentId) : null;
+    if (!owner || owner.status === "busy") { skipped.push(`${ws.id}:owner-busy`); continue; }
+
+    // Gate: skip if stored metadata shows WIP or commits ahead.
+    // The orchestrator re-checks live before mutating; stored data is a fast pre-filter.
+    const meta = ws.metadata as Record<string, unknown>;
+    const gitAhead = typeof meta.gitAhead === "number" ? meta.gitAhead : undefined;
+    const gitDirtyCount = typeof meta.gitDirtyCount === "number" ? meta.gitDirtyCount : undefined;
+    if (gitAhead !== undefined && gitAhead > 0) { skipped.push(`${ws.id}:ahead`); continue; }
+    if (gitDirtyCount !== undefined && gitDirtyCount > 0) { skipped.push(`${ws.id}:dirty`); continue; }
+
+    const command = createCommand({
+      type: "workspace.idle-refresh",
+      source: "system",
+      target: orch.agentId,
+      correlationId: ws.id,
+      params: {
+        workspaceId: ws.id,
+        repoRoot: ws.repoRoot,
+        worktreePath: ws.worktreePath,
+        branch: ws.branch,
+        baseRef: ws.baseRef,
+        baseSha: ws.baseSha,
+        requestedBy: "workspace-idle-refresh",
+        requestedAt: now,
+      },
+    });
+    emitCommand(command);
+    dispatched.push(ws.id);
+  }
+
+  return { dispatched, skipped };
+}
+
+/**
+ * Apply the result of a settled `workspace.idle-refresh` command.
+ * When the orchestrator refreshed the worktree, repoint the DB row to the
+ * new branch and update base_sha so the next merge targets the live branch.
+ */
+export function applyIdleRefreshResult(workspaceId: string, result: Record<string, unknown>): boolean {
+  const newBranch = typeof result.newBranch === "string" ? result.newBranch : undefined;
+  const baseSha = typeof result.baseSha === "string" ? result.baseSha : undefined;
+  if (!newBranch || result.refreshed !== true) return false;
+  setWorkspaceBranch(workspaceId, newBranch, baseSha);
+  return true;
+}

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/tools-spawn.ts

@@ -12,13 +12,15 @@ import { countLiveSpawnedAgents, listAgents, listWorkspaces, ValidationError } f
 import { listCommands } from "../commands-db";
 import { DEFAULT_SPAWN_PROFILE_NAME } from "../config-store";
 import { optionalEnum } from "../validation";
-import { APPROVAL_MODES, SPAWN_PROVIDERS, stringValue, VALID_AGENT_LIFECYCLES, VALID_EFFORTS, VALID_WORKSPACE_MODES } from "agent-relay-sdk";
+import { APPROVAL_MODES, AUTO_MERGE_POLICIES, SPAWN_PROVIDERS, stringValue, VALID_AGENT_LIFECYCLES, VALID_EFFORTS, VALID_WORKSPACE_MODES } from "agent-relay-sdk";
 import type { ProviderEffort } from "agent-relay-sdk/provider-catalog";
-import type { AgentCard, AgentLifecycle, Command, SpawnApprovalMode, SpawnProvider, WorkspaceMode, WorkspaceRecord } from "../types";
+import type { AgentCard, AgentLifecycle, Command, SpawnApprovalMode, SpawnProvider, WorkspaceAutoMergePolicy, WorkspaceLandingPolicy, WorkspaceMode, WorkspaceRecord } from "../types";
 import type { McpAuthContext, ToolDefinition } from "./types";
 import { callerAgentId } from "./identity";
 import { enumField, optionalBoolean, optionalNonNegativeInt, optionalPositiveInt, optionalString, optionalStringArray } from "./validation";
 
+const SPAWN_LAND_STRATEGIES = ["direct", "pr"] as const;
+
 export const SPAWN_TOOLS: ToolDefinition[] = [
   {
     name: "relay_spawn_agent",
@@ -48,6 +50,9 @@ export const SPAWN_TOOLS: ToolDefinition[] = [
           ],
           description: "#689 — shared host-listener MCP. Host-MCP profiles default ON: the worker's NON-IDENTITY MCP (tokenlean, github) is routed through one orchestrator-owned shared `callmux` listener via a per-agent `callmux bridge --cwd \"$WORKTREE\"`, so the MCP session survives listener/downstream restart and keeps isolated worktree cwd routing. Profiles that suppress host MCP stay OFF unless explicitly opted in. Pass `false` as a per-spawn kill-switch to force direct/per-agent MCP injection. The identity-bearing relay endpoint stays per-agent (#215), never on the shared listener.",
         },
+        landStrategy: { type: "string", enum: SPAWN_LAND_STRATEGIES, description: "#421 — per-spawn workspace land strategy. Omit to use the instance landing.strategy. `direct` keeps deterministic rebase/fast-forward landing; `pr` opens a PR." },
+        autoMerge: { type: "string", enum: AUTO_MERGE_POLICIES, description: "#421/#305 — PR auto-merge policy when landStrategy resolves to `pr`. `on-green` auto-merges after checks, `on-approval` waits for reviewer approval, `manual` opens the PR only." },
+        reviewer: { type: "string", description: "#421/#305 — optional reviewer handle or policy target for reviewer-first PR lands, used with landStrategy `pr` and autoMerge `on-approval`." },
         profile: { type: "string", description: `Agent profile name to apply (env, instructions, permissions, MCP/skills, spawn quota). Omit to use \`${DEFAULT_SPAWN_PROFILE_NAME}\`.` },
         tags: { type: "array", items: { type: "string" } },
         capabilities: { type: "array", items: { type: "string" } },
@@ -56,6 +61,16 @@ export const SPAWN_TOOLS: ToolDefinition[] = [
         spawnRequestId: { type: "string" },
         lifecycle: { type: "string", enum: VALID_AGENT_LIFECYCLES, description: "Lifecycle mode. `persistent` keeps the agent until explicitly stopped. `transient` lets Relay auto-shutdown the child after it is idle and, for isolated workers, after its branch has landed. Default: persistent." },
         workspaceMode: { type: "string", enum: VALID_WORKSPACE_MODES, description: "Git workspace for the worker. `isolated` = its own worktree on an `agent/session-*` branch off main that auto-lands when ready (delegate a unit of work, get a branch worker). `shared` = edits your live checkout (a sidecar). `inherit` = let the orchestrator decide. DEFAULT for agent-initiated spawns is `isolated` so a delegated worker lands to main instead of editing your tree; pass `shared`/`inherit` to override." },
+        resumeWorkspace: {
+          type: "object",
+          description: "#635 — attach a new worker to an EXISTING managed worktree/branch instead of always creating a fresh one. `attach`: reuse the worktree as-is (crash recovery — WIP is preserved); `branch-from`: fresh worktree off the existing branch HEAD (phased work, sequential hand-off). Guard: `attach` is rejected when the original owner is still alive. The resumed worker's branch auto-lands normally on completion.",
+          properties: {
+            branch: { type: "string", description: "The existing agent branch to attach to or branch from (e.g. `agent/build-389/.../...`)." },
+            mode: { type: "string", enum: ["attach", "branch-from"], description: "`attach` = reuse the existing worktree directory (WIP preserved). `branch-from` = fresh worktree off the branch HEAD (committed history carried, WIP not)." },
+          },
+          required: ["branch", "mode"],
+          additionalProperties: false,
+        },
         waitForRegistrationMs: { type: "integer", minimum: 0, maximum: 30000, description: "How long to wait for the spawned agent to register before returning, so the response carries its resolved agent id (default 8000; 0 = return immediately with just spawnRequestId)." },
       },
       required: ["provider"],
@@ -105,6 +120,15 @@ export const SPAWN_TOOLS: ToolDefinition[] = [
   },
 ];
 
+function parseResumeWorkspace(value: unknown): { branch: string; mode: "attach" | "branch-from" } | undefined {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return undefined;
+  const obj = value as Record<string, unknown>;
+  const branch = optionalString(obj.branch, "resumeWorkspace.branch", 500);
+  const mode = obj.mode === "attach" || obj.mode === "branch-from" ? obj.mode : undefined;
+  if (!branch || !mode) return undefined;
+  return { branch, mode };
+}
+
 export async function relaySpawnAgent(auth: McpAuthContext, args: Record<string, unknown>): Promise<Record<string, unknown>> {
   const input: SpawnAgentInput = {
     provider: enumField(args.provider, "provider", SPAWN_PROVIDERS) as SpawnProvider,
@@ -126,12 +150,16 @@ export async function relaySpawnAgent(auth: McpAuthContext, args: Record<string,
     projectSkills: parseProjectSkills(args.projectSkills, (m) => new ValidationError(m)),
     projectSettings: parseProjectSettings(args.projectSettings, (m) => new ValidationError(m)),
     sharedMcp: parseSharedMcp(args.sharedMcp, (m) => new ValidationError(m)),
+    landStrategy: optionalEnum(args.landStrategy, "landStrategy", SPAWN_LAND_STRATEGIES) as WorkspaceLandingPolicy | undefined,
+    autoMerge: optionalEnum(args.autoMerge, "autoMerge", AUTO_MERGE_POLICIES) as WorkspaceAutoMergePolicy | undefined,
+    reviewer: optionalString(args.reviewer, "reviewer", 240),
     tags: optionalStringArray(args.tags, "tags"),
     capabilities: optionalStringArray(args.capabilities, "capabilities"),
     providerArgs: optionalStringArray(args.providerArgs, "providerArgs"),
     spawnRequestId: optionalString(args.spawnRequestId, "spawnRequestId", 160),
     requestedVia: "mcp",
     waitForRegistrationMs: optionalNonNegativeInt(args.waitForRegistrationMs, "waitForRegistrationMs") ?? 8000,
+    resumeWorkspace: parseResumeWorkspace(args.resumeWorkspace),
   };
   const result = await spawnAgent(input, authContextFromMcp(auth));
   return { ...result };

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