agent-relay-runner 0.84.0 → 0.86.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-relay-runner",
-  "version": "0.84.0",
+  "version": "0.86.0",
   "description": "Unified provider lifecycle runner for Agent Relay",
   "type": "module",
   "bin": {
@@ -20,7 +20,7 @@
     "directory": "runner"
   },
   "dependencies": {
-    "agent-relay-sdk": "0.2.64"
+    "agent-relay-sdk": "0.2.66"
   },
   "devDependencies": {
     "@types/bun": "latest",

package/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.84.0",
+  "version": "0.86.0",
   "agentRelayContracts": {
     "providerPluginProtocol": 1
   }

package/plugins/claude/skills/reply/SKILL.md

@@ -20,11 +20,11 @@ Examples:
 ```bash
 agent-relay /reply 206 "Sounds good, I'll take a look"
 agent-relay /reply 42 "Done — the fix is in commit abc123"
-agent-relay /reply 42 --stdin < .agent-relay/sessions/$AGENT_RELAY_ID/tmp/reply.md
+agent-relay /reply 42 --body-file .agent-relay/sessions/$AGENT_RELAY_ID/tmp/reply.md
 agent-relay /reply 42 --body-file response.md
 ```
 
-Use `--stdin` or `--body-file` for long replies so shell quoting does not mangle the body. Oversized replies are automatically uploaded as an Agent Relay artifact and sent as an attached concise reply.
+Use `--body-file` for long replies so shell quoting does not mangle the body. Oversized replies are automatically uploaded as an Agent Relay artifact and sent as an attached concise reply.
 
 The relay creates this per-session scratch dir for you (it is git-ignored locally), so staging there never pollutes the working tree and never collides with other agents. No cleanup needed — the dir is reaped when your session ends.
 

package/plugins/codex/skills/reply/SKILL.md

@@ -20,11 +20,11 @@ Examples:
 ```bash
 agent-relay /reply 206 "Sounds good, I'll take a look"
 agent-relay /reply 42 "Done — the fix is in commit abc123"
-agent-relay /reply 42 --stdin < .agent-relay/sessions/$AGENT_RELAY_ID/tmp/reply.md
+agent-relay /reply 42 --body-file .agent-relay/sessions/$AGENT_RELAY_ID/tmp/reply.md
 agent-relay /reply 42 --body-file response.md
 ```
 
-Use `--stdin` or `--body-file` for long replies so shell quoting does not mangle the body. Oversized replies are automatically uploaded as an Agent Relay artifact and sent as an attached concise reply.
+Use `--body-file` for long replies so shell quoting does not mangle the body. Oversized replies are automatically uploaded as an Agent Relay artifact and sent as an attached concise reply.
 
 The relay creates this per-session scratch dir for you (it is git-ignored locally), so staging there never pollutes the working tree and never collides with other agents. No cleanup needed — the dir is reaped when your session ends.
 

package/src/adapter.ts

@@ -2,6 +2,7 @@ import type { AgentProfile, Message } from "agent-relay-sdk";
 import { isRecord } from "agent-relay-sdk";
 import type { SessionEvent } from "./session-insights";
 import { messageBodyMaxCharsFromEnv } from "./config";
+import { relayReplyReminderText } from "./relay-instructions";
 
 export type SemanticStatus = "idle" | "busy" | "offline" | "error";
 type ProviderWorkKind = "provider-turn" | "subagent" | "background-script";
@@ -204,7 +205,7 @@ export function profileIsVanillaBase(config: Pick<RunnerSpawnConfig, "agentProfi
   return config.agentProfile?.base === "vanilla";
 }
 
-export const RELAY_CONTEXT = `[agent-relay] You are connected to Agent Relay, a real-time message bus between agents and users. When you receive a relay message: read it, do what it asks, and reply through the relay when a text response is needed. Use agent-relay /react <messageId> <emoji> for lightweight acknowledgement or approval. If Relay MCP tools are available, prefer relay_reply, relay_get_message, relay_get_thread, relay_send_message, relay_upload_artifact, relay_attach_artifact, relay_agent_status, relay_find_agents, relay_compact_and_resume, relay_recall, relay_spawn_agent, and relay_shutdown_agent. You never need to know or pass your own agent id — relay fills it from your token; use relay_whoami only if you need to reason about yourself. relay_compact_and_resume is for clean-seam self-resume after a context advisory: pass workingState and optional ruledOut; Relay owns the objective envelope. relay_recall searches your own archived pre-compaction segments by keyword when a discarded detail is needed. relay_spawn_targets / relay_spawn_agent / relay_shutdown_agent only appear if your profile grants spawning (a live-children quota); when present, call relay_spawn_targets FIRST for the live host/provider/model matrix + your quota, then stand up long-living child agents and shut down your own — find them later with relay_find_agents spawnedBy:me. CLI fallback: agent-relay /reply <messageId> --stdin < response.md; if a delivered message says it was truncated, fetch the full body with: agent-relay get-message <messageId>. For command details, run: agent-relay /guide`;
+export const RELAY_CONTEXT = `[agent-relay] You are connected to Agent Relay, a real-time message bus between agents and users. When you receive a relay message: read it, do what it asks, and reply through the relay when a text response is needed. Use agent-relay /react <messageId> <emoji> for lightweight acknowledgement or approval. If Relay MCP tools are available, prefer relay_reply, relay_get_message, relay_get_thread, relay_send_message, relay_upload_artifact, relay_attach_artifact, relay_agent_status, relay_find_agents, relay_compact_and_resume, relay_recall, relay_spawn_agent, and relay_shutdown_agent. You never need to know or pass your own agent id — relay fills it from your token; use relay_whoami only if you need to reason about yourself. relay_compact_and_resume is for clean-seam self-resume after a context advisory: pass workingState and optional ruledOut; Relay owns the objective envelope. relay_recall searches your own archived pre-compaction segments by keyword when a discarded detail is needed. relay_spawn_targets / relay_spawn_agent / relay_shutdown_agent only appear if your profile grants spawning (a live-children quota); when present, call relay_spawn_targets FIRST for the live host/provider/model matrix + your quota, then stand up long-living child agents and shut down your own — find them later with relay_find_agents spawnedBy:me. For replies, prefer relay_reply or relay_send_message; CLI fallback: agent-relay /reply <messageId> "<your reply>". If a delivered message says it was truncated, fetch the full body with: agent-relay get-message <messageId>. For command details, run: agent-relay /guide`;
 
 // #306 — deliver the FULL message body by default. Only a pathological body beyond this
 // high cap truncates (with a get-message hint) so it can't nuke an agent's context; the 99%
@@ -353,7 +354,7 @@ export function providerMessageText(messages: Message[]): string {
           `[truncated: showing first ${maxChars} of ${message.body.length} chars]`,
           `Read full: agent-relay get-message ${message.id}`,
           `Body only: agent-relay get-message ${message.id} --body`,
-          `Long reply: agent-relay /reply ${message.id} --stdin < response.md`,
+          `Long reply CLI fallback: agent-relay /reply ${message.id} --body-file response.md`,
         ].join("\n")
         : undefined;
       if (isMemoryContext) {
@@ -375,7 +376,7 @@ export function providerMessageText(messages: Message[]): string {
   if (replyable) {
     sections.push([
       "[agent-relay reply reminder]",
-      `If this batch needs a response, send one useful reply to the latest relevant message: agent-relay /reply ${replyable.id} --stdin < response.md`,
+      relayReplyReminderText(replyable.id),
       "If you already delivered the useful response through Relay, do not send a separate status-only confirmation.",
       "If multiple messages arrived together, cover them in one reply instead of answering each line separately.",
     ].join("\n"));

package/src/adapters/claude-delivery.ts

@@ -1,6 +1,7 @@
 import type { Message } from "agent-relay-sdk";
 import { isRecord } from "agent-relay-sdk";
 import { isNotificationMessage, NOTIFICATION_NUDGE, providerAttachmentText, providerMessageBodyMaxChars } from "../adapter";
+import { relayReplyReminderText } from "../relay-instructions";
 
 const REMINDER_EVERY_DELIVERIES = 5;
 
@@ -112,10 +113,12 @@ function formatMessage(message: Message, relaySurface: boolean): string {
 function replyReminder(message: Message, readOnly: boolean): string {
   const command = readOnly
     ? `agent-relay /reply ${message.id} "<your reply>"`
-    : `agent-relay /reply ${message.id} --stdin < response.md`;
+    : relayReplyReminderText(message.id);
   return [
     "[agent-relay reply reminder]",
-    `If this batch needs a response, send one useful reply to the latest relevant message: ${command}`,
+    readOnly
+      ? `If this batch needs a response, send one useful reply to the latest relevant message: ${command}`
+      : command,
     "If you already delivered the useful response through Relay, do not send a separate status-only confirmation.",
     "If multiple messages arrived together, cover them in one reply instead of answering each line separately.",
   ].join("\n");

package/src/control-server.ts

@@ -3,6 +3,7 @@ import type { Message, ReplyObligation } from "agent-relay-sdk";
 import { errMessage, isRecord } from "agent-relay-sdk";
 import type { ProviderPermissionDecisionInput, ProviderStatusEvent, SemanticStatus, TerminalAttachSpec } from "./adapter";
 import { obligationRequiresExplicitReply } from "./reply-obligation-cache";
+import { relayReplyActionText } from "./relay-instructions";
 import { logger, parseLogLevel, LOG_LEVELS } from "./logger";
 import { buildRateLimitProviderState } from "./rate-limit";
 
@@ -197,7 +198,7 @@ function replyObligationSummary(obligations: ReplyObligation[]): Record<string,
     pending: true,
     count: obligations.length,
     obligation,
-    reason: `Pending Agent Relay response for message #${obligation.messageId} from ${obligation.from}${subject}. If it still needs an answer, run: ${obligation.replyCommand}. If multiple delivered messages are part of one current request, answer once to the latest relevant message. If the useful response was already delivered through Relay, do not send a separate status-only confirmation.`,
+    reason: `Pending Agent Relay response for message #${obligation.messageId} from ${obligation.from}${subject}. If it still needs an answer, use ${relayReplyActionText(obligation.messageId)}. If multiple delivered messages are part of one current request, answer once to the latest relevant message. If the useful response was already delivered through Relay, do not send a separate status-only confirmation.`,
   };
 }
 

package/src/relay-instructions.ts

@@ -3,7 +3,7 @@ export const CLAUDE_RELAY_MANUAL = `# Agent Relay
 - Agent Relay messages may come from humans, channels, or other agents.
 - Read the delivered message body and do the requested work.
 - Reply through Relay only when the sender still needs an answer.
-- Prefer \`agent-relay /reply <messageId> --stdin < response.md\` for the actual answer to an incoming Relay message.
+- Prefer the inline MCP tools \`relay_reply\` or \`relay_send_message\` for the actual answer to an incoming Relay message.
 - Do not send \`/message\` with the useful answer and then a separate \`/reply\` that only says it was sent.
 - If multiple Relay messages arrive together, answer once to the latest relevant message and cover the current request. Do not separately acknowledge stale greetings or context.
 - If the useful response was already delivered through Relay, do not send an extra "sent", "done", or "drafts sent" confirmation unless the user explicitly asked for one.
@@ -25,6 +25,14 @@ This Claude session is running with restricted read-only Relay permissions. Do n
 
 agent-relay /reply <messageId> "<your reply>"`;
 
+export function relayReplyActionText(messageId: number): string {
+  return `relay_reply (messageId: ${messageId}, body: "<your reply>"). CLI fallback: agent-relay /reply ${messageId} "<your reply>"`;
+}
+
+export function relayReplyReminderText(messageId: number): string {
+  return `If this batch needs a response, send one useful reply to the latest relevant message with ${relayReplyActionText(messageId)}`;
+}
+
 /**
  * Provider-agnostic caveat injected into every spawned agent that runs in an
  * isolated workspace, regardless of which project it is working in. Isolated

package/src/runner-core.ts

@@ -224,6 +224,11 @@ export class AgentRunner {
   private readonly mcpProxySecret: string;
   private process?: ManagedProcess;
   private stopped = false;
+  // #633 — set when the provider terminally exits but the runner stays alive (Claude native
+  // auto-compaction / manual-resume hold). Rides on the offline status frame so the server fires a
+  // terminal `agent.exited` event with a #636 diagnosis instead of the death going silent. Cleared
+  // on any genuine restart back to busy/idle.
+  private terminalProviderExit?: Record<string, unknown>;
   private exitCommandInProgress = false;
   private restartInProgress = false;
   // Set for the whole unexpected-exit restart, including the pre-restart backoff
@@ -1010,6 +1015,14 @@ export class AgentRunner {
           },
         });
         this.process = undefined;
+        // #633: the runner stays alive (manual-resume hold), so neither the orchestrator tmux-gone
+        // path nor the heartbeat reaper will ever fire. Stamp the terminal marker so the SAME offline
+        // status frame (published by setProviderStatus below) carries it; the server's bus status
+        // handler turns that edge into a terminal `agent.exited` event with a #636 diagnosis.
+        this.terminalProviderExit = {
+          reason: hasResumeId ? "claude-exit-manual-resume-available" : "claude-exit-manual-intervention-required",
+          ...diagnostics,
+        };
         this.setProviderStatus({
           status,
           reason: "provider-turn",
@@ -1241,6 +1254,9 @@ export class AgentRunner {
       // re-inject any pending spawner obligation so it surfaces the /reply command.
       if (this.options.provider !== "claude") void this.reInjectPendingObligation();
     }
+    // A genuine restart back to forward progress clears the terminal-exit marker so a later offline
+    // doesn't re-announce a stale provider exit.
+    if (status === "busy" || status === "idle") this.terminalProviderExit = undefined;
     if (status === "busy") {
       this.claims.clearTerminalStatus();
       this.claims.startWork(reason, id, typeof update === "string" ? {} : {
@@ -1828,6 +1844,14 @@ export class AgentRunner {
           terminalFailureReason: terminalFailure.reason,
           terminalFailureMessage: terminalFailure.message,
         } : {}),
+        // #633 — terminal provider-exit marker (runner alive, provider gone). Drives the server's
+        // silent-death terminal event + #636 post-mortem.
+        ...(this.terminalProviderExit ? {
+          terminalProviderExit: this.terminalProviderExit,
+          ...(typeof this.terminalProviderExit.claudeResumeId === "string"
+            ? { lastError: `Claude provider exited; resume id ${this.terminalProviderExit.claudeResumeId} captured for manual recovery` }
+            : { lastError: "Claude provider exited; manual intervention required" }),
+        } : {}),
         busyReasons: this.claims.reasons(),
         activeWork,
         activeSubagents,