agent-relay-server 0.118.3 → 0.118.5

package/docs/openapi.json

@@ -2,7 +2,7 @@
   "openapi": "3.1.0",
   "info": {
     "title": "Agent Relay API",
-    "version": "0.118.3",
+    "version": "0.118.5",
     "description": "Real-time message bus for inter-agent communication. Agent-first: this spec is designed for machine consumption — agents can self-discover the full API surface via GET /api/spec.",
     "license": {
       "name": "MIT",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-relay-server",
-  "version": "0.118.3",
+  "version": "0.118.5",
   "description": "Lightweight HTTP message relay for inter-agent communication across machines",
   "module": "src/index.ts",
   "type": "module",
@@ -36,7 +36,7 @@
     "CONTRIBUTING.md"
   ],
   "dependencies": {
-    "agent-relay-channels-host": "0.118.3",
+    "agent-relay-channels-host": "0.118.5",
     "agent-relay-providers": "0.104.1",
     "agent-relay-sdk": "0.2.101",
     "ajv": "^8.20.0"

package/runner/plugins/claude/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "agent-relay-runner",
   "description": "Thin Agent Relay runner bridge for Claude Code",
-  "version": "0.118.3",
+  "version": "0.118.5",
   "agentRelayContracts": {
     "providerPluginProtocol": 1
   }

package/src/notification-rules.ts

@@ -255,6 +255,7 @@ const SPAWN_LIFECYCLE_AUDIENCE_TYPES = [
   "agent.exited",
   "agent.spawn_failed",
   "agent.spawn_recovered",
+  "agent.transient_empty_reap",
 ] as const satisfies readonly NotificationType[];
 
 for (const type of SPAWN_LIFECYCLE_AUDIENCE_TYPES) {

package/src/notification-settings.ts

@@ -129,7 +129,7 @@ export function notificationTypeEnabled(config: NotificationsConfig, type: Notif
 function notificationToggleForType(type: NotificationType): NotificationToggleKey | null {
   if (type === "branch.landed" || type === "landed-failure") return "branchLanded";
   if (type === "agent.ready") return "agentReady";
-  if (type === "agent.exited") return "agentExited";
+  if (type === "agent.exited" || type === "agent.transient_empty_reap") return "agentExited";
   if (type === "agent.spawn_failed") return "agentSpawnFailed";
   return null;
 }

package/src/notification-types.ts

@@ -22,6 +22,7 @@ export type NotificationType =
   | "agent.exited"
   | "agent.spawn_failed"
   | "agent.spawn_recovered"
+  | "agent.transient_empty_reap"
   | "agent.context_threshold"
   | "agent.stuck_busy"
   | "agent.quota_threshold"
@@ -120,6 +121,7 @@ export const DEFAULT_TTL_MS: Record<NotificationType, number | null> = {
   "agent.exited": null,
   "agent.spawn_failed": null,
   "agent.spawn_recovered": null,
+  "agent.transient_empty_reap": null,
   "agent.context_threshold": 15 * MINUTES,
   "agent.stuck_busy": null,
   "agent.quota_threshold": 15 * MINUTES,

package/src/services/task-entity.ts

@@ -9,6 +9,7 @@ import {
   createDeliverableTask,
   deliverableTaskIdsByOwnerAgent,
   deliverableTaskIdsBySpawnRequestId,
+  getAgent,
   getTaskDetail,
   listDeliverableTaskSummaries,
   listDeliverableTasks,
@@ -34,6 +35,8 @@ import {
 import { emitTaskChanged } from "../sse";
 import type { Task, TaskDetail, TaskEvent, TaskGateState, TaskListItem } from "../types";
 import { removeSubscriptionsForTask } from "../db/notification-subscriptions";
+import { emitRelayEvent } from "../events";
+import { routeNotification } from "../notification-router";
 import { isAgentExitDoneWhen, stageSatisfiesDoneWhen } from "./task-done-when";
 import { autoSubscribeTaskCoordinator, emitTaskSemanticNotification, taskTransitionForStage, taskTransitionForStatus } from "./task-semantic-events";
 
@@ -187,11 +190,11 @@ export function taskEntityHistory(id: number): TaskEvent[] {
   return listTaskEvents(id);
 }
 
-// #889 — finalize bound tasks for an reaped agent whose doneWhen is "agent-exit" / "reaped".
+// #889 — finalize bound tasks for a reaped agent whose doneWhen is "agent-exit" / "reaped".
 // Called by the transient reaper after requesting shutdown so ephemeral run-and-exit workers
 // don't leave their auto-scaffolded Task stuck in_progress forever.
 // Never overrides an already-terminal status. Idempotent (reapedAt guard inside markTaskAgentReaped).
-export function finalizeEphemeralTasksOnReap(agentId: string, opts: { spawnRequestId?: string; reason?: string } = {}): number[] {
+export function finalizeEphemeralTasksOnReap(agentId: string, opts: { spawnRequestId?: string; reason?: string; producedWork?: boolean; evidence?: string } = {}): number[] {
   const ids = new Set<number>();
   for (const id of deliverableTaskIdsByOwnerAgent(agentId)) ids.add(id);
   if (opts.spawnRequestId) {
@@ -203,6 +206,15 @@ export function finalizeEphemeralTasksOnReap(agentId: string, opts: { spawnReque
     if (!task) continue;
     if (task.status === "done" || task.status === "failed" || task.status === "canceled") continue;
     if (!isAgentExitDoneWhen(task.doneWhen)) continue;
+    if (opts.producedWork === false) {
+      try {
+        setTaskEntityStatus(taskId, { status: "open", note: "worker reaped without producing work; task reopened for retry", actor: "task-lifecycle" });
+        notifyEmptyTransientReap(agentId, task, opts);
+      } catch {
+        // best-effort; failures must not surface into the reaper scan
+      }
+      continue;
+    }
     try {
       if (!task.reapedAt) markTaskAgentReaped(taskId, { agentId, reason: opts.reason ?? "agent-exit" });
       setTaskEntityStatus(taskId, { status: "done", note: "doneWhen=agent-exit satisfied by worker reap", actor: "task-lifecycle" });
@@ -213,3 +225,32 @@ export function finalizeEphemeralTasksOnReap(agentId: string, opts: { spawnReque
   }
   return finalized;
 }
+
+function notifyEmptyTransientReap(agentId: string, task: TaskDetail, opts: { spawnRequestId?: string; reason?: string; evidence?: string }): void {
+  const agent = getAgent(agentId);
+  const parent = agent?.spawnedBy;
+  const recipients = [...new Set([parent, task.createdBy].filter((value): value is string => Boolean(value && value.trim())))];
+  const payload = {
+    kind: "agent.transient_empty_reap",
+    agentId,
+    parent,
+    taskId: task.id,
+    taskTitle: task.title,
+    spawnRequestId: opts.spawnRequestId,
+    reason: opts.reason ?? "agent-exit",
+    evidence: opts.evidence ?? "no-produced-work",
+  };
+  emitRelayEvent({ type: "agent.transient_empty_reap", source: "task-lifecycle", subject: agentId, data: payload });
+  routeNotification({
+    type: "agent.transient_empty_reap",
+    scope: { agentId, parent, taskId: String(task.id) },
+    recipients,
+    message: {
+      subject: "Worker reaped without producing work",
+      body: `Worker \`${agentId}\` was reaped without producing work for Task #${task.id} (${task.title}). The task was reopened for retry instead of being marked done.`,
+      payload,
+      idempotencyKey: `task:${task.id}:empty-reap:${agentId}:${opts.reason ?? "agent-exit"}`,
+      replyExpected: false,
+    },
+  });
+}

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

@@ -105,24 +105,39 @@ export function resetCommitsAheadForTests(): void {
   _commitsAheadFn = defaultCommitsAhead;
 }
 
-function transientLandComplete(agentId: string): { complete: boolean; workspaceId?: string; status?: string; reason?: string } {
+function completedProviderTurns(agent: AgentCard): number {
+  const value = agent.meta?.completedProviderTurns;
+  return typeof value === "number" && Number.isFinite(value) && value > 0 ? value : 0;
+}
+
+function workspaceProducedWork(ws: WorkspaceRecord | undefined): boolean {
+  if (!ws) return false;
+  if (ws.status === "merged") return true;
+  return typeof ws.metadata.mergedAt === "number";
+}
+
+function transientLandComplete(agent: AgentCard): { complete: boolean; producedWork: boolean; workspaceId?: string; status?: string; reason?: string } {
+  const agentId = agent.id;
   const isolated = listWorkspaces({ ownerAgentId: agentId }).filter((ws) => ws.mode === "isolated");
-  if (!isolated.length) return { complete: true, reason: "no-isolated-workspace" };
+  if (!isolated.length) return { complete: true, producedWork: completedProviderTurns(agent) > 0, reason: "no-isolated-workspace" };
   const live = isolated.find((ws) => !TERMINAL_WORKSPACE_STATUSES.has(ws.status));
-  if (!live) return { complete: true, workspaceId: isolated[0]?.id, status: isolated[0]?.status, reason: "terminal-workspace" };
+  if (!live) {
+    const latest = isolated[0];
+    return { complete: true, producedWork: workspaceProducedWork(latest), workspaceId: latest?.id, status: latest?.status, reason: "terminal-workspace" };
+  }
   const mergedAt = typeof live.metadata.mergedAt === "number" ? live.metadata.mergedAt : undefined;
   const landReportedAt = typeof live.metadata.landReportedAt === "number" ? live.metadata.landReportedAt : undefined;
   if (live.status === "active" && mergedAt !== undefined && mergedAt > (landReportedAt ?? 0)) {
-    return { complete: true, workspaceId: live.id, status: live.status, reason: "recycled-after-land" };
+    return { complete: true, producedWork: true, workspaceId: live.id, status: live.status, reason: "recycled-after-land" };
   }
   // Fast-path (#629): a zero-commit branch has nothing to preserve — reap immediately
   // instead of holding it pending a land that will never happen. Only fires when the
   // branch is provably empty (count === 0); null (unknown/git error) falls through to
   // the safe #614 hold-pending bias below.
   if (live.status === "active" && _commitsAheadFn(live) === 0) {
-    return { complete: true, workspaceId: live.id, status: live.status, reason: "empty-branch" };
+    return { complete: true, producedWork: false, workspaceId: live.id, status: live.status, reason: "empty-branch" };
   }
-  return { complete: false, workspaceId: live.id, status: live.status, reason: "land-pending" };
+  return { complete: false, producedWork: false, workspaceId: live.id, status: live.status, reason: "land-pending" };
 }
 
 function notifyTransientHeld(agentId: string, workspaceId: string | undefined, status: string | undefined, waitMs: number): void {
@@ -171,11 +186,14 @@ export function reapTransientAgents(): Record<string, unknown> {
     // #800 — `reapProtected` is the single home for that decision: it honors only
     // evidence-based block states, never a high quota-utilization number.
     if (reapProtected(agent)) { transientTracker.delete(agent.id); continue; }
+    // A just-registered transient worker can briefly report idle/ready before its first provider
+    // turn starts. Do not start the idle-reap clock until the runner has observed a completed turn.
+    if (completedProviderTurns(agent) === 0) { transientTracker.delete(agent.id); waiting.push(agent.id); continue; }
     const entry = transientTracker.get(agent.id) ?? { firstIdleAt: now };
     transientTracker.set(agent.id, entry);
     const idleForMs = now - entry.firstIdleAt;
     if (idleForMs < grace) { waiting.push(agent.id); continue; }
-    const land = transientLandComplete(agent.id);
+    const land = transientLandComplete(agent);
     if (!land.complete) {
       if (idleForMs >= grace + maxLandWait) {
         held.push(agent.id);
@@ -201,7 +219,7 @@ export function reapTransientAgents(): Record<string, unknown> {
     // #889 — finalize any bound task whose doneWhen is "agent-exit" (auto-scaffolded ephemeral
     // tasks that produce no deliverable and would otherwise hang in_progress forever).
     const spawnRequestId = typeof agent.meta?.spawnRequestId === "string" ? agent.meta.spawnRequestId : undefined;
-    finalizeEphemeralTasksOnReap(agent.id, { spawnRequestId, reason: "transient-complete" });
+    finalizeEphemeralTasksOnReap(agent.id, { spawnRequestId, reason: "transient-complete", producedWork: land.producedWork, evidence: land.reason });
     reaped.push(agent.id);
   }
   for (const key of transientTracker.keys()) if (!seen.has(key)) transientTracker.delete(key);

package/src/workspace-auto-merge.ts

@@ -21,7 +21,6 @@
 import {
   createActivityEvent,
   getActiveMergePause,
-  getAgent,
   listOrchestrators,
   listWorkspaces,
   patchWorkspaceMetadata,
@@ -36,10 +35,10 @@ import { renderTemplate } from "./prompt-resolver";
 import { isAwaitingReviewerApproval } from "./reviewer-pipeline";
 import { emitWorkspaceTaskSemanticNotifications } from "./services/task-lifecycle";
 import { ensureRepoSteward } from "./steward";
-import { requestWorkspaceMerge } from "./workspace-merge";
+import { requestWorkspaceMerge, workspaceMergeOrchestrators } from "./workspace-merge";
 import { workspaceActiveClaim } from "./workspace-claim";
 import { DIRTY_WORKTREE_LAND_SKIP_REASON, READY_TO_LAND_STATUSES } from "./workspace-phase";
-import { fetchHostMergePreview, workspacePathWithinBase } from "./workspace-probe";
+import { fetchHostMergePreview } from "./workspace-probe";
 import type { WorkspaceAutoMergePolicy, WorkspaceLandingPolicy, WorkspaceMergePreview, WorkspaceMergeStrategy, WorkspaceRecord } from "./types";
 import { STEWARD_WAKE_COOLDOWN_MS, stewardFallbackTarget, workspaceAutoMergeEnabled } from "./config";
 
@@ -263,25 +262,11 @@ function emptyLandSweep(): LandSweepResult {
   return { scanned: 0, merged: [], heldByLease: [], heldByClaim: [], heldByPause: [], heldAwaitingApproval: [], previewUnavailable: [], backedOff: [], leftForSteward: [], wokeStewards: [] };
 }
 
-function workspaceOrchestrators(
-  ws: WorkspaceRecord,
-  orchestrators: ReturnType<typeof listOrchestrators>,
-): ReturnType<typeof listOrchestrators> {
-  const candidates = orchestrators.filter((candidate) => workspacePathWithinBase(ws.sourceCwd, candidate.baseDir));
-  const ownerMachine = ws.ownerAgentId ? getAgent(ws.ownerAgentId)?.machine : undefined;
-  if (!ownerMachine) return candidates;
-  return [...candidates].sort((a, b) => {
-    const aOwner = a.hostname === ownerMachine || a.id === ownerMachine ? 0 : 1;
-    const bOwner = b.hostname === ownerMachine || b.id === ownerMachine ? 0 : 1;
-    return aOwner - bOwner;
-  });
-}
-
 async function fetchFirstUsableMergePreview(
   ws: WorkspaceRecord,
   orchestrators: ReturnType<typeof listOrchestrators>,
 ): Promise<WorkspaceMergePreview | { available: false } | null> {
-  for (const orch of workspaceOrchestrators(ws, orchestrators)) {
+  for (const orch of workspaceMergeOrchestrators(ws, orchestrators)) {
     if (!orch.apiUrl) continue;
     const preview = await fetchHostMergePreview(orch.apiUrl, ws);
     if (!preview || (preview as { available?: false }).available === false) continue;

package/src/workspace-merge.ts

@@ -14,6 +14,7 @@ import {
 import { getLandingConfig } from "./config-store";
 import type {
   Command,
+  Orchestrator,
   WorkspaceAutoMergePolicy,
   WorkspaceLandingPolicy,
   WorkspaceMergeStrategy,
@@ -142,6 +143,39 @@ export function withOwnerOnline<T extends { ownerAgentId?: string }>(workspace:
   return { ...workspace, ownerOnline: isOwnerAlive(workspace.ownerAgentId) };
 }
 
+function workspaceOwnerHostKeys(workspace: WorkspaceRecord): Set<string> {
+  const keys = new Set<string>();
+  const owner = workspace.ownerAgentId ? getAgent(workspace.ownerAgentId) : undefined;
+  if (!owner) return keys;
+  if (owner.machine) keys.add(owner.machine);
+  const meta = isRecord(owner.meta) ? owner.meta : undefined;
+  const orchestratorId = meta ? stringValue(meta.orchestratorId) : undefined;
+  if (orchestratorId) keys.add(orchestratorId);
+  if (orchestratorId) keys.add(`orchestrator-${orchestratorId}`);
+  return keys;
+}
+
+/**
+ * Online hosts that can operate on a workspace, ordered by ownership first.
+ * The fallback to any matching host is intentional for manual recovery, but the
+ * owner host must win when known: isolated worktree paths are host-local.
+ */
+export function workspaceMergeOrchestrators(
+  workspace: WorkspaceRecord,
+  orchestrators: Orchestrator[] = listOrchestrators(),
+): Orchestrator[] {
+  const candidates = orchestrators.filter((candidate) =>
+    candidate.status === "online" && isPathWithinBase(workspace.sourceCwd, candidate.baseDir),
+  );
+  const ownerKeys = workspaceOwnerHostKeys(workspace);
+  if (ownerKeys.size === 0) return candidates;
+  return [...candidates].sort((a, b) => {
+    const aOwner = ownerKeys.has(a.id) || ownerKeys.has(a.hostname) || ownerKeys.has(a.agentId) ? 0 : 1;
+    const bOwner = ownerKeys.has(b.id) || ownerKeys.has(b.hostname) || ownerKeys.has(b.agentId) ? 0 : 1;
+    return aOwner - bOwner;
+  });
+}
+
 /**
  * Resolved cwds of every live (non-offline) agent, including the workspace sourceCwd
  * they were spawned in. The third "nobody is using it" signal the reaper needs: a
@@ -206,9 +240,7 @@ export function requestWorkspaceMerge(workspace: WorkspaceRecord, opts: RequestW
   }
   try {
     // Merge needs a live host: rebasing against a stale base later is unsafe.
-    const onlineOwner = listOrchestrators().find(
-      (candidate) => candidate.status === "online" && isPathWithinBase(workspace.sourceCwd, candidate.baseDir),
-    );
+    const onlineOwner = workspaceMergeOrchestrators(workspace)[0];
     if (!onlineOwner) {
       releaseMergeLease({ repoRoot: workspace.repoRoot, workspaceId: workspace.id });
       return { ok: false, status: 409, error: "no online orchestrator available for workspace merge" };