agent-relay-runner 0.85.0 → 0.87.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-relay-runner",
-  "version": "0.85.0",
+  "version": "0.87.0",
   "description": "Unified provider lifecycle runner for Agent Relay",
   "type": "module",
   "bin": {
@@ -20,7 +20,7 @@
     "directory": "runner"
   },
   "dependencies": {
-    "agent-relay-sdk": "0.2.65"
+    "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.85.0",
+  "version": "0.87.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

@@ -28,6 +28,7 @@ import { publishCapturedResponse } from "./response-capture-report";
 import { runnerLaunchInjectionSessionEvents, type RunnerRelayInjectionEvent } from "./relay-injection-events";
 import { providerTerminalSession, providerTerminalSocket } from "./process-meta";
 import { capsFromEnv, logLevelFromEnv, mcpProxyEnabledFromEnv, orchestratorBaseDirFromEnv, orchestratorUrlFromEnv, registrationTimeoutMsFromEnv, runnerInfoFileFromEnv, runnerLogFileFromEnv, runnerOutboxDirWithInfoFallback, sessionDebugEnabled, tagsFromEnv, workspaceModeFromEnv } from "./config";
+import { boundaryReasonForCommand, PRE_DESTROY_TIMEOUT_MS, reasonExitsRunner, type LifecycleAction, type SessionDestroyReason } from "./session-destroy";
 import {
   appliedAgentProfileMetadata,
   commandTimeoutMs,
@@ -55,48 +56,13 @@ import {
   type ProbeModelInfo,
 } from "./runner-helpers";
 
-// A destructive session transition. The runner runs end-of-session work (Insights
-// capture, #183/#184) before the invasive operation and, during that window, presents a
-// distinct non-addressable lifecycle state. Bus commands and provider hooks (Claude
-// PreCompact / SessionEnd) both normalize to one of these.
-type SessionDestroyReason = "compact" | "clear" | "restart" | "shutdown" | "kill" | "crash";
-
-// Reasons after which the runner process won't survive to drain the durable outbox (and the
-// per-agent outbox is never reopened once the agent is gone). For these, pre-destroy must
-// block on delivery of the just-captured Insights datapoint, not just enqueue it (#183).
-// `restart` (bus command) deliberately excluded: the runner stays alive and drains normally.
-function reasonExitsRunner(reason: SessionDestroyReason): boolean {
-  return reason === "shutdown" || reason === "kill" || reason === "crash";
-}
-
-// `finalizing-<reason>` is the transient pre-destroy window; the others are the executing
-// teardown states the dashboard already renders.
-type LifecycleAction =
-  | "shutting-down" | "killing" | "restarting"
-  | `finalizing-${SessionDestroyReason}`;
-
 // Pre-destroy work is best-effort and must never hang teardown. Capping it keeps a slow
 // transcript read or a wedged provider from stalling a shutdown the operator asked for.
-const PRE_DESTROY_TIMEOUT_MS = 4_000;
-
 // Bounded window to deliver the durable outbox before an exit-bound teardown (#183). Kept
 // short so a wedged/down server can't stall an operator-requested shutdown for long; a
 // row that still can't land is logged, not silently dropped.
 const OUTBOX_FLUSH_TIMEOUT_MS = 3_000;
 
-// Map a lifecycle bus command to its destructive boundary reason, or undefined for
-// non-destructive commands (interrupt, inject, reconnect, permission decisions).
-function boundaryReasonForCommand(type: string): SessionDestroyReason | undefined {
-  switch (type) {
-    case "agent.compact": return "compact";
-    case "agent.clearContext": return "clear";
-    case "agent.restart": return "restart";
-    case "agent.shutdown": return "shutdown";
-    case "agent.kill": return "kill";
-    default: return undefined;
-  }
-}
-
 interface RunnerOptions {
   provider: string;
   model?: string;
@@ -258,6 +224,7 @@ export class AgentRunner {
   private readonly pendingMessages = new Map<number, Message>();
   private readonly activeTaskClaims = new Map<number, ActiveTaskClaim>();
   private pendingTimelineEvent?: RunnerTimelineEvent;
+  private lastProviderEventAt?: number;
   private pendingPromptMessageId?: number;
   // #329: a spawn-time initial prompt whose first delivery timed out before the TUI was
   // ready. Held (not dropped) for a ready-signal-driven re-attempt; cleared on success.
@@ -1167,6 +1134,7 @@ export class AgentRunner {
 
   private setProviderStatus(update: ProviderStatusUpdate): void {
     const status = typeof update === "string" ? update : update.status;
+    this.lastProviderEventAt = Date.now();
     const providerSessionId = typeof update === "string" ? undefined : update.providerSessionId;
     if (providerSessionId && providerSessionId !== this.providerSessionId) return;
     const reason = typeof update === "string" ? "provider-turn" : update.reason ?? "provider-turn";
@@ -1856,6 +1824,7 @@ export class AgentRunner {
         activeWork,
         activeSubagents,
         activeSubagentCount: activeSubagents.length,
+        ...(this.lastProviderEventAt !== undefined ? { lastProviderEventAt: this.lastProviderEventAt } : {}),
         providerState,
         auth: {
           profileId: this.currentTokenProfileId ?? null,

package/src/runner-insights.ts

@@ -1,12 +1,11 @@
 import type { WorkspaceMetadata } from "agent-relay-sdk";
 import type { ManagedProcess, ProviderAdapter } from "./adapter";
 import type { Outbox } from "./outbox";
+import type { SessionDestroyReason } from "./session-destroy";
 import { resolveProjectName } from "./config";
 import { computeContextRatio } from "./session-insights";
 import { boundContinuationArchiveSegment } from "./continuation-archive";
 
-type SessionDestroyReason = "compact" | "clear" | "restart" | "shutdown" | "kill" | "crash";
-
 interface RunnerInsightsDeps {
   agentId: string;
   cwd: string;

package/src/session-destroy.ts

@@ -0,0 +1,22 @@
+export type SessionDestroyReason = "compact" | "clear" | "restart" | "shutdown" | "kill" | "crash";
+
+export type LifecycleAction =
+  | "shutting-down" | "killing" | "restarting"
+  | `finalizing-${SessionDestroyReason}`;
+
+export const PRE_DESTROY_TIMEOUT_MS = 4_000;
+
+export function reasonExitsRunner(reason: SessionDestroyReason): boolean {
+  return reason === "shutdown" || reason === "kill" || reason === "crash";
+}
+
+export function boundaryReasonForCommand(type: string): SessionDestroyReason | undefined {
+  switch (type) {
+    case "agent.compact": return "compact";
+    case "agent.clearContext": return "clear";
+    case "agent.restart": return "restart";
+    case "agent.shutdown": return "shutdown";
+    case "agent.kill": return "kill";
+    default: return undefined;
+  }
+}