agent-relay-server 0.121.4 → 0.121.5

package/docs/openapi.json

@@ -2,7 +2,7 @@
   "openapi": "3.1.0",
   "info": {
     "title": "Agent Relay API",
-    "version": "0.121.4",
+    "version": "0.121.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.121.4",
+  "version": "0.121.5",
   "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.4",
+    "agent-relay-channels-host": "0.121.5",
     "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.4",
+  "version": "0.121.5",
   "agentRelayContracts": {
     "providerPluginProtocol": 1
   }

package/src/bus.ts

@@ -1,5 +1,5 @@
 import type { Server, ServerWebSocket } from "bun";
-import { ValidationError, getAgent, getDb, heartbeat, markReady, mergeAgentMeta, orphanTasksForAgent, revokeRuntimeTokensForAgent, setStatus, validateAgentSession } from "./db";
+import { ValidationError, getAgent, getDb, heartbeat, markReady, mergeAgentMeta, orphanTasksForAgent, setStatus, validateAgentSession } from "./db";
 import { getOutboxCursor, hasReplayGap, replayEventsSlice, type BusEvent } from "./bus-outbox";
 import { projectAgentStatusData } from "./agent-card-projection";
 import { emitRelayEvent, subscribeRelayEvents, type RelayEvent } from "./events";
@@ -127,9 +127,11 @@ export function expireStaleBusAgents(graceMs = busStaleGraceMs(), lagGraceMs = 0
   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) {
-    // Bus-grace staleness across a relay restart/reconnect — the process may be alive.
-    // Tag "stale" so a live runner self-heals via orchestrator re-mint (#484).
-    revokeRuntimeTokensForAgent(row.id, Date.now(), "stale");
+    // #1051 — bus-grace staleness is a liveness observation, not a credential fact: the
+    // process may still be alive (relay stall / network blip). Mark offline for routing,
+    // but do NOT revoke the token — a reconnect accepts the EXISTING token and re-marks
+    // live. The #484 restart-strand revoke now fires on instance takeover in registerAgent
+    // (a fresh instanceId → epoch bump), never on a heartbeat lapse.
     setStatus(row.id, "offline");
     emitAgentStatusEvent(row.id);
     // #1040 — the stale sweep is the terminal busy→offline edge for a runner that dropped without a

package/src/db/agents.ts

@@ -505,10 +505,13 @@ export function reapStaleAgents(ttlMs: number = STALE_TTL_MS, lagGraceMs = 0): s
     )
     .all(cutoff) as any[];
   for (const row of rows) {
-    // Staleness == last_seen lapsed, which is exactly the relay-restart strand: the
-    // process may still be alive. Tag "stale" so a live runner can self-heal via an
-    // orchestrator re-mint (#484); a genuinely-dead one never re-mints and is pruned.
-    revokeRuntimeTokensForAgent(row.id, now, "stale");
+    // #1051 — liveness ≠ credential validity. A lapsed heartbeat is a transient,
+    // recoverable observation (the relay may have stalled, or the network blipped);
+    // it marks status only and must NOT void a still-unexpired token. On reconnect the
+    // relay accepts the agent's EXISTING token and re-marks it live. The #484 restart-
+    // strand invariant (an orphaned prior-instance token must not stay usable) is now
+    // enforced on instance takeover instead — see revokeSupersededRuntimeTokens, fired
+    // from registerAgent when a fresh process re-registers under a new instanceId.
     closeOpenPairsForAgent(row.id, now);
   }
   return rows.map((r: any) => r.id);
@@ -589,6 +592,28 @@ export function deleteAgent(id: string): { ok: boolean; error?: string } {
 export function revokeRuntimeTokensForAgent(agentId: string, now = Date.now(), reason: TokenRevokeReason = "agent-removed"): string[] {
   const row = getDb().query("SELECT meta FROM agents WHERE id = ?").get(agentId) as { meta?: string } | undefined;
   const jtis = runtimeTokenJtisFromMeta(parseJson(row?.meta ?? "{}", {}));
+  return revokeProviderRuntimeTokensByJti(jtis, reason, now);
+}
+
+// #1051 — the #484 restart-strand invariant, re-homed from heartbeat-lapse to instance
+// takeover. Staleness (a missed heartbeat) no longer revokes anything; instead, when a
+// FRESH runner process re-registers under an existing agent id — a new instanceId, which
+// bumps the agent epoch (see upsertAgent) — the PRIOR instance's runtime tokens are
+// revoked "stale" here. "stale" (not a hard kill) keeps them re-mintable via the
+// orchestrator (#484), so a live process that merely rotated instances still self-heals,
+// while an orphaned prior-instance token can no longer authenticate a request directly.
+// The incoming instance's own token (already stamped into the NEW meta) is preserved: a
+// same-instance reconnect (relay-restart / lag recovery) keeps its instanceId, does not
+// bump the epoch, and so never reaches this path — its token stays valid untouched.
+export function revokeSupersededRuntimeTokens(prior: AgentCard, current: AgentCard, now = Date.now()): string[] {
+  const priorJtis = runtimeTokenJtisFromMeta((prior.meta ?? {}) as Record<string, unknown>);
+  if (priorJtis.length === 0) return [];
+  const keep = new Set(runtimeTokenJtisFromMeta((current.meta ?? {}) as Record<string, unknown>));
+  const superseded = priorJtis.filter((jti) => !keep.has(jti));
+  return revokeProviderRuntimeTokensByJti(superseded, "stale", now);
+}
+
+function revokeProviderRuntimeTokensByJti(jtis: string[], reason: TokenRevokeReason, now: number): string[] {
   if (jtis.length === 0) return [];
   const revokedAt = Math.floor(now / 1000);
   const placeholders = jtis.map(() => "?").join(",");

package/src/managed-policy.ts

@@ -1,6 +1,8 @@
 import { getManifest } from "agent-relay-providers";
+import { DEFAULT_USER_ID } from "agent-relay-sdk";
 import { getAgentProfile } from "./config-store";
-import { withResolvedProvisioning } from "./db";
+import { resolveProjectForCwd, resolveScopedAnchor, withResolvedProvisioning } from "./db";
+import { composeSpawnInstructionsWithEvents } from "./project-instructions";
 import { runnerRuntimeTokenEnv } from "./runtime-tokens";
 import { buildSpawnCommand, resolveSpawnModelParams } from "./spawn-command";
 import { applyDefaultSharedMcp } from "./shared-mcp";
@@ -10,11 +12,19 @@ function managedPolicyPromptMode(policy: SpawnPolicy): "prompt" | "append-system
   return getManifest(policy.provider)?.launch?.managedPolicyPrompt?.alwaysOn ?? "prompt";
 }
 
-export function managedPolicyProviderArgs(policy: SpawnPolicy): string[] {
+/**
+ * The always-on keepalive prompt an `append-system-prompt`-mode provider (Claude) carries as a
+ * system-prompt append (Codex uses the launch `prompt` channel instead — see
+ * `managedPolicyLaunchPrompt`). Returns undefined when it does not apply. #1052 folds this into
+ * `composeSpawnInstructionsWithEvents` as the caller append so there is a SINGLE ordered
+ * `--append-system-prompt` block (profile role charter + project knowledge + this keepalive),
+ * instead of a second stray `--append-system-prompt` arg that could stack on the composed one.
+ */
+export function managedPolicyAppendSystemPrompt(policy: SpawnPolicy): string | undefined {
   if (policy.mode === "always-on" && policy.prompt?.trim() && managedPolicyPromptMode(policy) === "append-system-prompt") {
-    return [...policy.providerArgs, "--append-system-prompt", policy.prompt.trim()];
+    return policy.prompt.trim();
   }
-  return policy.providerArgs;
+  return undefined;
 }
 
 export function managedPolicyLaunchPrompt(policy: SpawnPolicy): string | undefined {
@@ -33,10 +43,35 @@ interface ManagedSpawnContext {
 }
 
 export function buildManagedSpawnParams(policy: SpawnPolicy, requestId: string, ctx: ManagedSpawnContext): Record<string, unknown> {
-  const providerArgs = managedPolicyProviderArgs(policy);
   const prompt = managedPolicyLaunchPrompt(policy);
   const resolvedProfile = withResolvedProvisioning(policy.profile ? getAgentProfile(policy.profile)?.value : undefined, policy.provider);
   const agentProfile = resolvedProfile ? applyDefaultSharedMcp(resolvedProfile) : undefined;
+
+  // #1052 — run the SAME instruction projection a fresh interactive spawn gets
+  // (composeSpawnInstructionsWithEvents, the single home in spawn-agent.ts), so a MANAGED agent
+  // (e.g. the always-on coordinator) is onboarded IDENTICALLY on its first launch AND on every
+  // restart / deploy-bounce relaunch — this builder feeds both `spawnAgent` and `restartAgent`.
+  // Previously the managed path forwarded only `agentProfile` (for provisioning) + providerArgs
+  // and silently dropped the profile ROLE CHARTER (`instructions.system`/`append`), project-
+  // knowledge preamble, and scoped {profile|user} memory, so a restarted coordinator reverted to
+  // provider-default IC behavior until a human re-injected the role file (#1052). The always-on
+  // keepalive prompt folds in as the caller append → one ordered `--append-system-prompt` block,
+  // no double-inject. The projection is deterministic (sorted + deduped), so re-running it on a
+  // native-resume relaunch reproduces a byte-identical block rather than stacking a second copy.
+  const callerProject = resolveProjectForCwd(policy.cwd) ?? undefined;
+  const projectInstructions = agentProfile?.projectInstructions;
+  const profileAnchor = policy.profile ? resolveScopedAnchor("profile", policy.profile) ?? undefined : undefined;
+  const userAnchor = resolveScopedAnchor("user", DEFAULT_USER_ID) ?? undefined;
+  const alwaysOnAppend = managedPolicyAppendSystemPrompt(policy);
+  const composed = composeSpawnInstructionsWithEvents({
+    ...(callerProject ? { callerProject } : {}),
+    ...(projectInstructions ? { projectInstructions } : {}),
+    ...(profileAnchor ? { profileAnchor } : {}),
+    ...(userAnchor ? { userAnchor } : {}),
+    ...(agentProfile ? { profile: agentProfile } : {}),
+    ...(alwaysOnAppend ? { callerSystemPromptAppend: alwaysOnAppend } : {}),
+  });
+
   return buildSpawnCommand({
     provider: policy.provider,
     orchestratorId: policy.orchestratorId,
@@ -51,8 +86,10 @@ export function buildManagedSpawnParams(policy: SpawnPolicy, requestId: string,
     capabilities: policy.capabilities,
     approvalMode: policy.permissionMode,
     permissionMode: policy.permissionMode,
-    providerArgs,
+    providerArgs: policy.providerArgs,
     prompt: prompt || undefined,
+    ...(composed.systemPromptAppend ? { systemPromptAppend: composed.systemPromptAppend } : {}),
+    ...(composed.relayInjectionEvents.length ? { relayInjectionEvents: composed.relayInjectionEvents } : {}),
     headless: true,
     policyName: policy.name,
     spawnRequestId: requestId,

package/src/services/register-agent.ts

@@ -10,7 +10,7 @@
 // status broadcast, the single timeline note, the spawned-child parent-wake, and
 // the first-registration audit row.
 import { errMessage, isReservedAgentId } from "agent-relay-sdk";
-import { ValidationError, createActivityEvent, deliverableTaskIdsBySpawnRequestId, getAgent, getTaskDetail, mergeAgentMeta, readSpawnReportVerbosity, seedSpawnPromptMirror, seedSpawnReplyObligation, upsertAgent } from "../db";
+import { ValidationError, createActivityEvent, deliverableTaskIdsBySpawnRequestId, getAgent, getTaskDetail, mergeAgentMeta, readSpawnReportVerbosity, revokeSupersededRuntimeTokens, seedSpawnPromptMirror, seedSpawnReplyObligation, upsertAgent } from "../db";
 import { emitAgentStatus, emitNewMessage } from "../sse";
 import { noteAgentTimelineEvent } from "../compaction-watch";
 import { agentProviderTimelineEvent } from "../provider-timeline-event";
@@ -93,6 +93,17 @@ export function registerAgent(input: RegisterAgentInput, ctx: AuthContext): Agen
   if (existing) delete registrationInput.label;
   const agent = upsertAgent(registrationInput);
 
+  // #1051/#484 — instance takeover is where the restart-strand invariant fires now that a
+  // heartbeat lapse no longer revokes anything. When a FRESH runner process re-registers
+  // under this agent id (new instanceId → epoch bump), revoke the PRIOR instance's runtime
+  // tokens "stale": they can no longer authenticate a request directly, yet stay re-mintable
+  // via the orchestrator (#484). A same-instance reconnect keeps its instanceId, so the epoch
+  // is unchanged and the live token is left valid — the whole point of #1051 (in-band recovery
+  // after lag/relay-restart without a re-mint).
+  if (existing?.instanceId && agent.instanceId && existing.instanceId !== agent.instanceId) {
+    revokeSupersededRuntimeTokens(existing, agent);
+  }
+
   // Managed came-up-running reconcile — no-op for non-managed agents (the guard lives
   // in markManagedAgentRunning). Clears backoff, flushes the policy queue, transitions
   // managed state to running.