agent-relay-server 0.118.4 → 0.118.5

package/docs/openapi.json

@@ -2,7 +2,7 @@
   "openapi": "3.1.0",
   "info": {
     "title": "Agent Relay API",
-    "version": "0.118.4",
+    "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.4",
+  "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.4",
+    "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.4",
+  "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);