agent-relay-server 0.121.1 → 0.121.3

package/docs/openapi.json

@@ -2,7 +2,7 @@
   "openapi": "3.1.0",
   "info": {
     "title": "Agent Relay API",
-    "version": "0.121.1",
+    "version": "0.121.3",
     "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.121.1",
+  "version": "0.121.3",
   "description": "Lightweight HTTP message relay for inter-agent communication across machines",
   "module": "src/index.ts",
   "type": "module",
@@ -37,7 +37,7 @@
     "CONTRIBUTING.md"
   ],
   "dependencies": {
-    "agent-relay-channels-host": "0.121.1",
+    "agent-relay-channels-host": "0.121.3",
     "agent-relay-providers": "0.104.3",
     "agent-relay-sdk": "0.2.113",
     "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.121.1",
+  "version": "0.121.3",
   "agentRelayContracts": {
     "providerPluginProtocol": 1
   }

package/src/bus.ts

@@ -118,8 +118,12 @@ export function getBusConnectionCount(): number {
   return busConnections.size;
 }
 
-export function expireStaleBusAgents(graceMs = busStaleGraceMs()): { agentIds: string[]; orphanedTasks: Task[] } {
-  const cutoff = Date.now() - graceMs;
+export function expireStaleBusAgents(graceMs = busStaleGraceMs(), lagGraceMs = 0): { agentIds: string[]; orphanedTasks: Task[] } {
+  // #1048 defense-in-depth: subtract the relay's own recently-observed event-loop lag
+  // from the cutoff so a bus-grace expiry can't fire on a heartbeat gap that was really
+  // the relay stalling. Secondary to the stale reaper (this only touches already-`stale`
+  // rows), but kept symmetric. lagGraceMs is passed in — bus.ts stays health-agnostic.
+  const cutoff = Date.now() - graceMs - Math.max(0, lagGraceMs);
   const rows = getDb().query("SELECT id FROM agents WHERE status = 'stale' AND last_seen < ? AND id NOT IN ('user', 'system')").all(cutoff) as Array<{ id: string }>;
   const orphanedTasks: Task[] = [];
   for (const row of rows) {
@@ -170,7 +174,12 @@ function handleFrame(ws: BusWebSocket, frame: ReturnType<typeof validateClientFr
               // frame. Flush the held report-up on THIS edge too, else `before.status` is already
               // non-busy at the next status frame → the flush never fires → the child deadlocks idle
               // with its verdict held and the coordinator waits forever.
-              if (current?.status === "busy" && frame.payload.status !== "busy") flushIdleLineageReport(conn.agentId);
+              // #1037 (re-regression) — gate on a genuine at-rest `idle`, NOT merely "not busy". A
+              // real turn-end always reports `idle`; a transient non-idle status (a stray `online`,
+              // a malformed frame) is NOT the end of the child's work and must not flush its held
+              // mid-work capture upstream. Terminal exit edges (WS-close/stale sweep) keep their
+              // unconditional flush for the #1040 delivery guarantee — this only tightens the LIVE edge.
+              if (current?.status === "busy" && frame.payload.status === "idle") flushIdleLineageReport(conn.agentId);
             }
             emitAgentStatusEvent(conn.agentId);
             // #416 — flush queued messages if the agent transitioned from unavailable to available.
@@ -216,8 +225,11 @@ function handleFrame(ws: BusWebSocket, frame: ReturnType<typeof validateClientFr
         // #237 stop-hook → instant ⚪↔🟡 changes detection on the turn-end edge.
         probeWorkspaceOnTurnEnd(before, after);
         // #1037 — the same busy→idle turn-end edge flushes a quiet child's deferred turn-final
-        // report-up to its spawner (held back while the child was mid-work).
-        if (before?.status === "busy" && after && after.status !== "busy") flushIdleLineageReport(conn.agentId);
+        // report-up to its spawner (held back while the child was mid-work). Gate on a genuine
+        // at-rest `idle`: a real turn-end reports `idle`, whereas a transient non-idle status
+        // (stray `online`, reconnect) is not the child going to rest and must not flush its held
+        // mid-work capture. Terminal exit edges keep the #1040 unconditional flush.
+        if (before?.status === "busy" && after && after.status === "idle") flushIdleLineageReport(conn.agentId);
         // #633 — silent clean-exit: a runner that stays alive after its provider terminally exited
         // marks the offline edge with `terminalProviderExit`; the owning service turns that into a
         // terminal event + #636 diagnosis (and clears the hold on a genuine resume).

package/src/db/agents.ts

@@ -491,9 +491,13 @@ function mergeRelayContextMarkers(agentId: string, next: ContextState | undefine
 }
 
 
-export function reapStaleAgents(ttlMs: number = STALE_TTL_MS): string[] {
+export function reapStaleAgents(ttlMs: number = STALE_TTL_MS, lagGraceMs = 0): string[] {
   const now = Date.now();
-  const cutoff = now - ttlMs;
+  // #1048 — extend the stale cutoff by the relay's own recently-observed event-loop
+  // lag. A missed heartbeat while THIS process was stalled means "the relay couldn't
+  // read it", not "the agent died"; the caller passes the grace in (this module stays
+  // health-agnostic). lagGraceMs of 0 is the pre-#1048 behavior.
+  const cutoff = now - ttlMs - Math.max(0, lagGraceMs);
   getDb().query("UPDATE agents SET last_seen = ? WHERE id IN ('user', 'system')").run(now);
   const rows = getDb()
     .query(

package/src/db/messages.ts

@@ -347,6 +347,40 @@ function childIsBusy(child: AgentCard): boolean {
   return child.status === "busy";
 }
 
+// #1037 (re-regression) — the report-up must reach the spawner as a CONCISE result, not the full
+// turn transcript. In `chatCaptureMode: "full"` (and for rambling multi-block recaps) the captured
+// turn-final body is the ENTIRE turn's narration — every "Let me read X… now Y… now Z…" segment
+// joined by the canonical `\n\n` block boundary (runner extractLastAssistantTurn). Forwarding it
+// verbatim floods the coordinator with a wall of mid-work text (the exact bug #1037 keeps
+// re-shipping). Idle-gating alone can't help: this is a genuine turn-final at a genuine idle, so
+// the payload itself must be distilled. Short bodies pass through untouched (concise finals are
+// unaffected); a long body is trimmed to its trailing result block(s) — a turn's conclusion lives
+// at its end — with an elision marker so the coordinator knows narration was dropped. The actual
+// result is never lost. Pure function of the body → deterministic, so re-promotion (the idle flush)
+// yields the identical distilled body + idempotency key and dedups cleanly.
+const REPORT_UP_DISTILL_THRESHOLD = 800;
+const REPORT_UP_TAIL_MAX = 800;
+const REPORT_UP_ELISION = "[…mid-work narration trimmed by report-up…]";
+
+function distillLineageReportBody(body: string): string {
+  const trimmed = body.trim();
+  if (trimmed.length <= REPORT_UP_DISTILL_THRESHOLD) return body;
+  const blocks = trimmed.split(/\n{2,}/).map((block) => block.trim()).filter(Boolean);
+  const kept: string[] = [];
+  let size = 0;
+  for (let i = blocks.length - 1; i >= 0; i--) {
+    const block = blocks[i]!;
+    if (kept.length > 0 && size + block.length > REPORT_UP_TAIL_MAX) break;
+    kept.unshift(block);
+    size += block.length + 2;
+  }
+  let tail = kept.join("\n\n");
+  // A single oversized trailing block (unsegmented narration) — hard-cap to its own tail.
+  if (tail.length > REPORT_UP_TAIL_MAX) tail = tail.slice(tail.length - REPORT_UP_TAIL_MAX).replace(/^\S*\s/, "").trimStart();
+  if (tail.length >= trimmed.length) return body; // nothing meaningful trimmed
+  return `${REPORT_UP_ELISION}\n\n${tail}`;
+}
+
 // #1037 — a quiet child's turn-final response that arrives while the child is still busy is a
 // mid-task yield, not the end of its work. Instead of shipping it upstream (mid-work narration) or
 // dropping it (a genuine last turn whose idle status simply hasn't landed yet), we HOLD the latest
@@ -493,7 +527,9 @@ export function promoteLineageCapturedResponse(message: Message): { message: Mes
     from: message.from,
     to: parent,
     kind: "chat",
-    body: message.body,
+    // #1037 — distill the turn-final report-up to a concise result; verbose child-stream captures
+    // (an explicit subscriber that asked for the raw stream) are forwarded untouched.
+    body: stream === "responses" ? distillLineageReportBody(message.body) : message.body,
     replyExpected: false,
     idempotencyKey,
     payload: stream === "responses"

package/src/event-loop-lag.ts

@@ -43,9 +43,18 @@ export function recordEventLoopLagSample(lagMs: number, sampledAt: number = Date
   }
 }
 
-export function getEventLoopLagSnapshot(): EventLoopLagSnapshot {
+// Max lag over the retained ring buffer. SIDE-EFFECT-FREE: unlike
+// getEventLoopLagSnapshot it does NOT reset maxSinceLastReadMs, so a caller that
+// only needs the recent-lag ceiling (the stale reaper's grace, #1048) can read it
+// without stealing the spike the /health poller owns.
+export function eventLoopLagMaxMs(): number {
   let maxMs = 0;
   for (let i = 0; i < sampleCount; i += 1) maxMs = Math.max(maxMs, samples[i] ?? 0);
+  return maxMs;
+}
+
+export function getEventLoopLagSnapshot(): EventLoopLagSnapshot {
+  const maxMs = eventLoopLagMaxMs();
   const maxSinceLastRead = maxSinceLastReadMs;
   maxSinceLastReadMs = 0;
   return {

package/src/maintenance/jobs.ts

@@ -1,6 +1,7 @@
 import { getArtifactStorage } from "../artifact-storage";
 import { deriveAgentBusyHealth } from "../agent-busy-health";
 import { expireStaleBusAgents } from "../bus";
+import { eventLoopLagMaxMs } from "../event-loop-lag";
 import { pruneOutbox } from "../bus-outbox";
 import { expireCommands } from "../commands-db";
 import { getRetentionConfig } from "../retention-config-store";
@@ -277,7 +278,7 @@ export const definitions: MaintenanceJobDefinition[] = [
     intervalMs: REAP_INTERVAL_MS,
     runOnStart: true,
     handler() {
-      const expired = expireStaleBusAgents();
+      const expired = expireStaleBusAgents(undefined, eventLoopLagMaxMs());
       for (const id of expired.agentIds) {
         getLifecycleManager().onAgentDisappeared(id);
         // #636/#659 — only after the stale reconnect grace expires do we turn a bare
@@ -300,7 +301,12 @@ export const definitions: MaintenanceJobDefinition[] = [
     intervalMs: REAP_INTERVAL_MS,
     runOnStart: true,
     handler() {
-      const reapedAgentIds = reapStaleAgents(STALE_TTL_MS);
+      // #1048 — gate staleness on the relay's OWN event-loop health. eventLoopLagMaxMs()
+      // is side-effect-free (does not consume the /health poller's spike max). During a
+      // relay self-stall this grace keeps live agents whose heartbeats we simply couldn't
+      // process from being reaped as dead.
+      const lagGraceMs = eventLoopLagMaxMs();
+      const reapedAgentIds = reapStaleAgents(STALE_TTL_MS, lagGraceMs);
       for (const id of reapedAgentIds) {
         emitAgentStatus(id);
         createActivityEvent({

package/src/routes/workspaces.ts

@@ -7,7 +7,7 @@ import { WORKSPACE_ACTIONS, applyWorkspaceAction, buildWorkspaceCleanupCommand,
 import { auditEvent, authAuditMetadata, authorizeRoute, emitCommand, error, json, parseBody, type Handler } from "./_shared";
 import { collectWorkspaceOrphans } from "../workspace-orphans";
 import { createCommand } from "../commands-db";
-import { LAND_STRATEGIES, isOwnerAlive, withOwnerOnline } from "../workspace-merge";
+import { LAND_STRATEGIES, isOwnerAlive, isOwnerProcessConfirmedGone, withOwnerOnline } from "../workspace-merge";
 import { isPathWithinBase } from "../utils";
 import { resolve } from "node:path";
 import { type WorkspaceAutoMergePolicy, type WorkspaceDiagnostics, type WorkspaceGitState, type WorkspaceMergeStrategy, type WorkspaceRecoveryBranch, type WorkspaceRecord, type WorkspaceStatus } from "../types";
@@ -340,8 +340,14 @@ async function fetchWorkspaceGitState(workspace: WorkspaceRecord): Promise<{ sta
   }
 }
 
-function recommendWorkspaceAction(input: { workspace: WorkspaceRecord; ownerOnline: boolean; gitState?: WorkspaceGitState; claim: ReturnType<typeof workspaceActiveClaim> }): WorkspaceDiagnostics["recommendation"] {
-  const { workspace, ownerOnline, gitState, claim } = input;
+function recommendWorkspaceAction(input: { workspace: WorkspaceRecord; ownerOnline: boolean; ownerProcessGone: boolean; gitState?: WorkspaceGitState; claim: ReturnType<typeof workspaceActiveClaim> }): WorkspaceDiagnostics["recommendation"] {
+  const { workspace, ownerOnline, ownerProcessGone, gitState, claim } = input;
+  // #1049 — `!ownerOnline` is a heartbeat lapse, which a relay self-stall fakes for LIVE
+  // agents (the 2026-07-04 cascade). It must NOT alone drive a destructive recommendation.
+  // Treat the owner as genuinely gone only when its process death was actually observed
+  // (orchestrator-reported exit); otherwise a maybe-alive owner gets recovery, not a nuke.
+  const ownerGone = !ownerOnline && ownerProcessGone;
+  const awaitingReview = workspace.status === "review_requested" || workspace.status === "conflict";
   if (claim) return { action: "wait", confidence: "high", reason: `claimed by ${claim.by ?? "steward"}` };
   if (TERMINAL_WORKSPACE_STATUSES.has(workspace.status)) return { action: "none", confidence: "high", reason: `workspace is ${workspace.status}` };
   if (!gitState || gitState.error) return { action: "review", confidence: "low", reason: gitState?.error ? `git state error: ${gitState.error}` : "git state unavailable" };
@@ -350,19 +356,31 @@ function recommendWorkspaceAction(input: { workspace: WorkspaceRecord; ownerOnli
   const landed = gitState.landed === true;
   if ((gitState.dirtyCount ?? 0) > 0) return { action: "review", confidence: "medium", reason: `${gitState.dirtyCount} uncommitted change(s)` };
   if (ahead === 0 || landed) {
-    if (!ownerOnline) return { action: "cleanup", confidence: "high", reason: landed ? "work already landed; owner offline" : "no unmerged commits; owner offline" };
+    if (!ownerOnline) {
+      if (ownerGone) return { action: "cleanup", confidence: "high", reason: landed ? "work already landed; owner process gone" : "no unmerged commits; owner process gone" };
+      // Offline but the process wasn't observed dying — likely a false exit (relay stall /
+      // transport gap). Don't clean up; surface for review so a live owner can reconnect.
+      return { action: "review", confidence: "medium", reason: landed ? "work already landed; owner offline but process not confirmed gone — recover, don't clean up" : "owner offline but process not confirmed gone — recover, don't clean up" };
+    }
     // Owner active but the workspace is awaiting attention with nothing to land (#230):
     // landing it is a safe no-op that resolves it to terminal `merged`, clearing the
     // queue (the host keeps a live owner's worktree). Otherwise there's genuinely
     // nothing to do.
-    if (workspace.status === "review_requested" || workspace.status === "conflict") {
+    if (awaitingReview) {
       return { action: "merge", confidence: "high", reason: landed ? "work already landed; resolve the no-op" : "nothing to merge; resolve the no-op" };
     }
     return { action: "none", confidence: "medium", reason: "nothing to merge; owner active" };
   }
-  if (ownerOnline && workspace.status !== "review_requested" && workspace.status !== "conflict") {
+  if (ownerOnline && !awaitingReview) {
     return { action: "wait", confidence: "medium", reason: "owner active and not awaiting review" };
   }
+  // ahead > 0 with the owner offline. A worker that explicitly signaled review/conflict
+  // before going offline asked for the land — honor it. But a worker that merely lapsed
+  // mid-work (not awaiting review) with its process NOT confirmed gone is a false-exit
+  // candidate; recommend recovery, never an auto-land of its unmerged commits (#1049).
+  if (!ownerOnline && !awaitingReview && !ownerGone) {
+    return { action: "review", confidence: "medium", reason: `${ahead} unmerged commit(s) but owner offline and process not confirmed gone — recover, don't land` };
+  }
   if (workspace.status === "conflict") return { action: "rebase", confidence: "high", reason: "conflict — rebase onto base and resolve" };
   if ((gitState.behind ?? 0) > 0) return { action: "rebase", confidence: "medium", reason: `${gitState.behind} behind base — rebase then merge` };
   return { action: "merge", confidence: "high", reason: `${ahead} commit(s) ready to land` };
@@ -397,7 +415,7 @@ export const getWorkspaceDiagnostics: Handler = async (_req, params) => {
     orchestrator: { id: orch?.id, online: orchOnline },
     ...(claim ? { claim: { by: claim.by, purpose: claim.purpose, expiresAt: claim.expiresAt } } : {}),
     ...(gitState ? { gitState } : { gitStateUnavailable: "unavailable" in fetched ? fetched.unavailable : "unknown" }),
-    recommendation: recommendWorkspaceAction({ workspace, ownerOnline, gitState, claim }),
+    recommendation: recommendWorkspaceAction({ workspace, ownerOnline, ownerProcessGone: isOwnerProcessConfirmedGone(workspace.ownerAgentId), gitState, claim }),
   };
   return json(diagnostics);
 };

package/src/security.ts

@@ -476,6 +476,21 @@ export function unauthorized(req: Request): Response {
   return applyCors(req, response);
 }
 
+// #1047 — the MCP endpoint speaks JSON-RPC, so a 401 must be a JSON-RPC error
+// envelope, not the bare {"error":"unauthorized"} body (which fails client schema
+// validation and reads as protocol noise). Mirrors the runner proxy's own auth
+// failure (runner/src/relay-mcp-proxy.ts). id is null: the coarse auth gate runs
+// before the JSON-RPC body is parsed, and a revoked-token caller can't be trusted
+// to have supplied a well-formed id anyway.
+export function unauthorizedMcp(req: Request): Response {
+  const response = Response.json(
+    { jsonrpc: "2.0", id: null, error: { code: -32001, message: "unauthorized: session invalid or expired" } },
+    { status: 401 },
+  );
+  response.headers.set("WWW-Authenticate", "Bearer");
+  return applyCors(req, response);
+}
+
 function authToken(): string {
   return relayToken();
 }

package/src/server.ts

@@ -39,6 +39,7 @@ import {
   isScopedRequestAuthorized,
   isOriginAllowed,
   unauthorized,
+  unauthorizedMcp,
 } from "./security";
 import { startMaintenanceScheduler } from "./maintenance";
 import { RELAY_TOKEN_HEADER } from "agent-relay-sdk";
@@ -304,6 +305,11 @@ export function createFetchHandler(
           url.pathname.startsWith("/api/settings/");
         if (!isAuthorized(req)) {
           if (!integrationAuth) {
+            // #1047 — the MCP endpoint must fail with a JSON-RPC envelope, not the bare
+            // 401 body. This gate runs BEFORE postMcp (whose mcpAuthContext falls back to
+            // full server scope), so it stays the authoritative reject for a revoked/
+            // invalid session token — it just answers in the caller's protocol.
+            if (url.pathname === "/api/mcp") return unauthorizedMcp(req);
             return unauthorized(req);
           }
           if (!handlerOwnsScopedAuth && !isScopedRequestAuthorized(req)) return forbidden(req);

package/src/workspace-merge.ts

@@ -144,6 +144,22 @@ export function withOwnerOnline<T extends { ownerAgentId?: string }>(workspace:
   return { ...workspace, ownerOnline: isOwnerAlive(workspace.ownerAgentId) };
 }
 
+// #1049 — process-level death, distinct from "offline". `offline` is set on a mere
+// heartbeat lapse (exactly what a relay self-stall fakes for a batch of LIVE agents,
+// the 2026-07-04 cascade). A genuine process exit is only known when the owning
+// orchestrator REPORTS it: it stamps `meta.lastExit` (routes/orchestrator.ts). So
+// require both offline AND a reported exit before treating the owner as gone — never
+// nuke/land a worktree on a heartbeat gap alone. Conservative by design: an unmanaged
+// agent with no orchestrator never gets `lastExit`, so it reads as maybe-alive and the
+// orphan reaper's land-safety + grace window handle its eventual cleanup instead.
+export function isOwnerProcessConfirmedGone(ownerAgentId: string | undefined): boolean {
+  if (!ownerAgentId) return false;
+  const agent = getAgent(ownerAgentId);
+  if (!agent || agent.status !== "offline") return false;
+  const meta = isRecord(agent.meta) ? agent.meta : undefined;
+  return Boolean(meta && meta.lastExit);
+}
+
 function workspaceOwnerHostKeys(workspace: WorkspaceRecord): Set<string> {
   const keys = new Set<string>();
   const owner = workspace.ownerAgentId ? getAgent(workspace.ownerAgentId) : undefined;