agent-relay-server 0.59.0 → 0.60.0

package/src/reviewer-pipeline.ts

@@ -3,7 +3,7 @@ import { planSend } from "./agent-ref";
 import { createCommand } from "./commands-db";
 import { getSpawnPolicy } from "./config-store";
 import { getLifecycleManager } from "./lifecycle-manager";
-import { notifySystemMessage } from "./notify";
+import { routeNotification } from "./notification-router";
 import { getWorkspace, listAgents, patchWorkspaceMetadata, updateWorkspaceStatus } from "./db";
 import type { Command, WorkspaceMergePreview, WorkspaceRecord } from "./types";
 
@@ -60,26 +60,33 @@ export function handleReviewerMergeResult(command: Command, result: Record<strin
   });
   if (!updated) return false;
 
-  notifySystemMessage(target, {
-    subject: `Review requested: ${workspace.branch ?? workspace.id}`,
-    body: [
-      `Review PR ${prUrl ?? `#${prNumber ?? "unknown"}`} for workspace \`${workspace.id}\`.`,
-      `Repo: ${workspace.repoRoot}`,
-      workspace.branch ? `Branch: ${workspace.branch}` : undefined,
-      workspace.baseRef ? `Base: ${workspace.baseRef}` : undefined,
-      compareRef ? `Compare: ${compareRef}` : undefined,
-      "Approve the PR to let Relay arm GitHub auto-merge, or request changes to send it back to the workspace owner.",
-    ].filter(Boolean).join("\n"),
-    payload: {
-      kind: "workspace.review-request",
-      workspaceId: workspace.id,
-      repoRoot: workspace.repoRoot,
-      worktreePath: workspace.worktreePath,
-      branch: workspace.branch,
-      baseRef: workspace.baseRef,
-      prUrl,
-      prNumber,
-      compareRef,
+  // Obligation (ttl null by type default): a review request must reach the reviewer even if they're
+  // offline a while — it's not a bystander notice.
+  routeNotification({
+    type: "workspace.review_request",
+    scope: { workspaceId: workspace.id, repoRoot: workspace.repoRoot },
+    recipients: [target],
+    message: {
+      subject: `Review requested: ${workspace.branch ?? workspace.id}`,
+      body: [
+        `Review PR ${prUrl ?? `#${prNumber ?? "unknown"}`} for workspace \`${workspace.id}\`.`,
+        `Repo: ${workspace.repoRoot}`,
+        workspace.branch ? `Branch: ${workspace.branch}` : undefined,
+        workspace.baseRef ? `Base: ${workspace.baseRef}` : undefined,
+        compareRef ? `Compare: ${compareRef}` : undefined,
+        "Approve the PR to let Relay arm GitHub auto-merge, or request changes to send it back to the workspace owner.",
+      ].filter(Boolean).join("\n"),
+      payload: {
+        kind: "workspace.review-request",
+        workspaceId: workspace.id,
+        repoRoot: workspace.repoRoot,
+        worktreePath: workspace.worktreePath,
+        branch: workspace.branch,
+        baseRef: workspace.baseRef,
+        prUrl,
+        prNumber,
+        compareRef,
+      },
     },
   });
   if (policyName) getLifecycleManager().onMessageForPolicy(policyName);
@@ -172,26 +179,33 @@ function notifyReviewChangesRequested(
 ): string | undefined {
   const target = workspace.ownerAgentId;
   if (!target) return undefined;
-  notifySystemMessage(target, {
-    subject: `Changes requested: ${workspace.branch ?? workspace.id}`,
-    body: [
-      `The reviewer requested changes on ${prUrl ?? `PR #${prNumber ?? "unknown"}`}.`,
-      `Workspace \`${workspace.id}\` remains in review_requested.`,
-      preview.baseRef ? `Base: ${preview.baseRef}` : undefined,
-    ].filter(Boolean).join("\n"),
-    payload: {
-      kind: "workspace.review-changes-requested",
-      workspaceId: workspace.id,
-      repoRoot: workspace.repoRoot,
-      worktreePath: workspace.worktreePath,
-      branch: workspace.branch,
-      baseRef: workspace.baseRef,
-      prUrl,
-      prNumber,
-      reviewDecision: preview.reviewDecision,
-      statusCheckRollup: preview.statusCheckRollup,
+  // Durable (ttl null): the owner must learn changes were requested on THEIR workspace even after
+  // being offline — store-ahead, not a freshness-gated bystander notice.
+  routeNotification({
+    type: "workspace.review_changes_requested",
+    scope: { workspaceId: workspace.id, repoRoot: workspace.repoRoot, author: target },
+    recipients: [target],
+    message: {
+      subject: `Changes requested: ${workspace.branch ?? workspace.id}`,
+      body: [
+        `The reviewer requested changes on ${prUrl ?? `PR #${prNumber ?? "unknown"}`}.`,
+        `Workspace \`${workspace.id}\` remains in review_requested.`,
+        preview.baseRef ? `Base: ${preview.baseRef}` : undefined,
+      ].filter(Boolean).join("\n"),
+      payload: {
+        kind: "workspace.review-changes-requested",
+        workspaceId: workspace.id,
+        repoRoot: workspace.repoRoot,
+        worktreePath: workspace.worktreePath,
+        branch: workspace.branch,
+        baseRef: workspace.baseRef,
+        prUrl,
+        prNumber,
+        reviewDecision: preview.reviewDecision,
+        statusCheckRollup: preview.statusCheckRollup,
+      },
+      replyExpected: false,
     },
-    replyExpected: false,
   });
   return target;
 }

package/src/self-resume.ts

@@ -11,7 +11,7 @@ import {
   ValidationError,
 } from "./db";
 import { emitRelayEvent } from "./events";
-import { notifySystemMessage } from "./notify";
+import { routeNotification } from "./notification-router";
 import type { AgentCard, Command, ContinuationEnvelope, ContinuationLedgerEntry, SelfResumeMode } from "./types";
 
 export interface CompactAndResumeInput {
@@ -200,11 +200,16 @@ function notifySelfResumeBudgetExhausted(agent: AgentCard, envelope: Continuatio
   };
   emitRelayEvent({ type: "agent.resume_budget_exhausted", source: "server", subject: agent.id, data: payload });
   if (!agent.spawnedBy) return;
-  notifySystemMessage(agent.spawnedBy, {
-    subject: "Self-resume budget exhausted",
-    body: `Spawned agent \`${agent.id}\` stopped cleanly: ${reason}.`,
-    payload,
-    replyExpected: false,
+  routeNotification({
+    type: "agent.resume_budget_exhausted",
+    scope: { agentId: agent.id, parent: agent.spawnedBy },
+    recipients: [agent.spawnedBy],
+    message: {
+      subject: "Self-resume budget exhausted",
+      body: `Spawned agent \`${agent.id}\` stopped cleanly: ${reason}.`,
+      payload,
+      replyExpected: false,
+    },
   });
 }
 

package/src/services/plan-live-bindings.ts

@@ -1,6 +1,6 @@
 import { getTeam } from "../db";
 import { subscribeRelayEvents, type RelayEvent } from "../events";
-import { notifySystemMessage } from "../notify";
+import { routeNotification } from "../notification-router";
 import { updateBoundPlanNodesForAgent, updateBoundPlanNodesFromAgent } from "./plan-graph";
 
 let unsubscribe: (() => void) | undefined;
@@ -48,11 +48,16 @@ function notifyBoundExit(event: RelayEvent, updatedPlans: ReturnType<typeof upda
     const target = team?.coordinatorId ?? `team:${plan.teamId}`;
     const blockedNodes = plan.nodes.filter((node) => node.statusSource === "bound" && node.ownerRef?.agentId === agentId && node.status === "blocked");
     if (blockedNodes.length === 0) continue;
-    notifySystemMessage(target, {
-      subject: "Bound plan node blocked",
-      body: `Agent \`${agentId}\` exited${reason ? ` (${reason})` : ""}; blocked plan node(s) ${blockedNodes.map((node) => `\`${node.id}\``).join(", ")} in \`${plan.id}\`.`,
-      payload: { kind: "plan.bound_agent_exited", planId: plan.id, agentId, nodeIds: blockedNodes.map((node) => node.id), reason },
-      replyExpected: false,
+    routeNotification({
+      type: "plan.bound_agent_exited",
+      scope: { agentId, planId: plan.id, teamId: plan.teamId },
+      recipients: [target],
+      message: {
+        subject: "Bound plan node blocked",
+        body: `Agent \`${agentId}\` exited${reason ? ` (${reason})` : ""}; blocked plan node(s) ${blockedNodes.map((node) => `\`${node.id}\``).join(", ")} in \`${plan.id}\`.`,
+        payload: { kind: "plan.bound_agent_exited", planId: plan.id, agentId, nodeIds: blockedNodes.map((node) => node.id), reason },
+        replyExpected: false,
+      },
     });
   }
 }

package/src/services/rate-limit-resume.ts

@@ -1,5 +1,5 @@
 import { createActivityEvent, listAgents } from "../db";
-import { notifySystemMessage } from "../notify";
+import { routeNotification } from "../notification-router";
 import { agentProviderState, isRateLimitHold, rateLimitResumeAt } from "../provider-state";
 
 // #286 Phase 2: auto-resume agents held on a usage/rate-limit stall once their
@@ -52,16 +52,23 @@ export function resumeRateLimitedAgents(): Record<string, unknown> {
     resumeTracker.set(agent.id, now);
 
     try {
-      notifySystemMessage(agent.id, {
-        subject: "Usage limit reset — resume",
-        body: RESUME_BODY,
-        payload: {
-          kind: "agent.rate_limit_resume",
-          agentId: agent.id,
-          resetAt: state?.resetAt,
-          errorType: state?.errorType,
+      // Short default TTL (per-type): a "limit reset, resume" push is pointless once stale — the
+      // window has moved on. One recipient per iteration keeps the per-agent rollback below intact.
+      routeNotification({
+        type: "agent.rate_limit_resume",
+        scope: { agentId: agent.id },
+        recipients: [agent.id],
+        message: {
+          subject: "Usage limit reset — resume",
+          body: RESUME_BODY,
+          payload: {
+            kind: "agent.rate_limit_resume",
+            agentId: agent.id,
+            resetAt: state?.resetAt,
+            errorType: state?.errorType,
+          },
+          replyExpected: false,
         },
-        replyExpected: false,
       });
     } catch {
       // A stale/unreachable target must never break the sweep; it store-aheads

package/src/services/transient-agent-reaper.ts

@@ -1,7 +1,7 @@
 import { createCommand } from "../commands-db";
 import { emitRelayEvent } from "../events";
 import { createActivityEvent, getAgent, listAgents, listWorkspaces } from "../db";
-import { notifySystemMessage } from "../notify";
+import { routeNotification } from "../notification-router";
 import { isProviderBlocked } from "../provider-state";
 import { TERMINAL_WORKSPACE_STATUSES } from "../workspace-phase";
 
@@ -47,11 +47,16 @@ function notifyTransientHeld(agentId: string, workspaceId: string | undefined, s
     metadata: { source: "server", maintenanceJobId: "transient-agent-reaper", ...payload },
   });
   if (parent) {
-    notifySystemMessage(parent, {
-      subject: "Transient worker held pending land",
-      body: `Transient agent \`${agentId}\` is idle but still unreaped because workspace \`${workspaceId ?? "unknown"}\` is \`${status ?? "unknown"}\` after ${Math.round(waitMs / 60_000)} min. Its work is being preserved; resolve the land before cleanup.`,
-      payload,
-      replyExpected: false,
+    routeNotification({
+      type: "agent.transient_land_hold",
+      scope: { agentId, parent, workspaceId },
+      recipients: [parent],
+      message: {
+        subject: "Transient worker held pending land",
+        body: `Transient agent \`${agentId}\` is idle but still unreaped because workspace \`${workspaceId ?? "unknown"}\` is \`${status ?? "unknown"}\` after ${Math.round(waitMs / 60_000)} min. Its work is being preserved; resolve the land before cleanup.`,
+        payload,
+        replyExpected: false,
+      },
     });
   }
 }

package/src/token-db.ts

@@ -57,7 +57,7 @@ const BUILT_IN_PROFILES: Array<Omit<TokenProfile, "createdAt" | "updatedAt">> =
     name: "Provider Agent",
     description: "Coding-agent runtime access for messages, commands, tasks, and scoped memory reads.",
     role: "provider",
-    scope: ["agent:read", "agent:write", "message:read", "message:send", "command:read", "command:write", "task:read", "task:write", "memory:read", "artifact:read", "artifact:write", "mcp:use", "plans:read", "plans:write", "teams:read", "teams:write", "blackboard:read", "blackboard:write", "project:read", "project:write", "insights:write"],
+    scope: ["agent:read", "agent:write", "message:read", "message:send", "command:read", "command:write", "task:read", "task:write", "memory:read", "artifact:read", "artifact:write", "mcp:use", "plans:read", "plans:write", "teams:read", "teams:write", "blackboard:read", "blackboard:write", "project:read", "project:write", "notifications:read", "notifications:write", "insights:write"],
     ttlSeconds: 24 * 60 * 60,
     builtIn: true,
     createdBy: "system",
@@ -67,7 +67,7 @@ const BUILT_IN_PROFILES: Array<Omit<TokenProfile, "createdAt" | "updatedAt">> =
     name: "Provider Child Agent",
     description: "Delegated child-agent runtime access, constrained to its parent and spawn request.",
     role: "provider",
-    scope: ["agent:read", "agent:write", "message:read", "message:send", "command:read", "command:write", "task:read", "task:write", "memory:read", "artifact:read", "artifact:write", "mcp:use", "teams:read", "blackboard:read", "blackboard:write", "project:read", "project:write", "insights:write"],
+    scope: ["agent:read", "agent:write", "message:read", "message:send", "command:read", "command:write", "task:read", "task:write", "memory:read", "artifact:read", "artifact:write", "mcp:use", "teams:read", "blackboard:read", "blackboard:write", "project:read", "project:write", "notifications:read", "notifications:write", "insights:write"],
     constraints: { canDelegate: false },
     ttlSeconds: 2 * 60 * 60,
     builtIn: true,
@@ -78,7 +78,7 @@ const BUILT_IN_PROFILES: Array<Omit<TokenProfile, "createdAt" | "updatedAt">> =
     name: "Provider Interactive Agent",
     description: "User-launched provider runtime access constrained to its own agent and cwd for long interactive sessions.",
     role: "provider",
-    scope: ["agent:read", "agent:write", "message:read", "message:send", "command:read", "command:write", "task:read", "task:write", "memory:read", "artifact:read", "artifact:write", "mcp:use", "teams:read", "blackboard:read", "blackboard:write", "project:read", "project:write", "insights:write"],
+    scope: ["agent:read", "agent:write", "message:read", "message:send", "command:read", "command:write", "task:read", "task:write", "memory:read", "artifact:read", "artifact:write", "mcp:use", "teams:read", "blackboard:read", "blackboard:write", "project:read", "project:write", "notifications:read", "notifications:write", "insights:write"],
     constraints: { terminalAttach: false, logsRead: false, canDelegate: false },
     ttlSeconds: 30 * 24 * 60 * 60,
     builtIn: true,

package/src/workspace-pr-completion.ts

@@ -65,14 +65,21 @@ const PASSING_CONCLUSIONS = new Set(["SUCCESS", "NEUTRAL", "SKIPPED"]);
 const PASSING_STATES = new Set(["SUCCESS"]);
 const READY_MERGE_STATES = new Set(["CLEAN", "HAS_HOOKS"]);
 
-function relayPrMergeAlreadyHandled(workspace: WorkspaceRecord): boolean {
+function relayPrMergeAlreadyHandled(workspace: WorkspaceRecord, preview: WorkspaceMergePreview): boolean {
   const commandId = text(workspace.metadata.relayMergeCommandId);
-  if (commandId) {
-    const command = getCommand(commandId);
-    if (command && ACTIVE_COMMAND_STATUSES.has(command.status)) return true;
-    if (command?.status === "succeeded" && command.result?.relayMerged === true) return true;
-  }
-  return workspace.metadata.relayMerged === true && !commandId;
+  if (!commandId) return false;
+  const command = getCommand(commandId);
+  if (!command) return false;
+  // PR-scope the idempotency guard (#453). A land-and-continue recycle (#423) repoints the
+  // workspace onto a fresh branch but leaves the PRIOR cycle's relayMerge* metadata on the row,
+  // so without this a succeeded merge for an already-closed PR would block every SUBSEQUENT PR
+  // on the recycled workspace forever (green PR, never merged, no steward). Only treat the merge
+  // as already-handled when the recorded command targets the SAME PR we're now considering.
+  const recordedPr = isRecord(command.params) && typeof command.params.prNumber === "number" ? command.params.prNumber : undefined;
+  const currentPr = preview.prNumber ?? (typeof workspace.metadata.prNumber === "number" ? workspace.metadata.prNumber : undefined);
+  if (typeof recordedPr === "number" && typeof currentPr === "number" && recordedPr !== currentPr) return false;
+  if (ACTIVE_COMMAND_STATUSES.has(command.status)) return true;
+  return command.status === "succeeded" && command.result?.relayMerged === true;
 }
 
 function nativeAutoMergeArmed(workspace: WorkspaceRecord): boolean {
@@ -99,7 +106,7 @@ function prReadyForRelayMerge(workspace: WorkspaceRecord, preview: WorkspaceMerg
   if (preview.prMerged === true || preview.prState === "merged") return { ok: false, reason: "already-merged" };
   if (!preview.prNumber && !preview.prUrl) return { ok: false, reason: "missing-pr" };
   if (nativeAutoMergeArmed(workspace)) return { ok: false, reason: "native-auto-merge-armed" };
-  if (relayPrMergeAlreadyHandled(workspace)) return { ok: false, reason: "relay-merge-already-dispatched" };
+  if (relayPrMergeAlreadyHandled(workspace, preview)) return { ok: false, reason: "relay-merge-already-dispatched" };
 
   const policy = prAutoMergePolicy(workspace, preview);
   if (policy === "manual") return { ok: false, reason: "manual", policy };