agent-relay-server 0.23.0 → 0.24.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-relay-server",
-  "version": "0.23.0",
+  "version": "0.24.0",
   "description": "Lightweight HTTP message relay for inter-agent communication across machines",
   "module": "src/index.ts",
   "type": "module",

package/public/index.html

@@ -11391,6 +11391,14 @@ function agentPresence(now, agent, attention, pair) {
 		reconnecting: false,
 		badges
 	};
+	if (lifecycleAction.startsWith("finalizing-")) return {
+		label: `wrapping up (${lifecycleAction.slice(11)})`,
+		tone: "warning",
+		icon: "Hourglass",
+		stale,
+		reconnecting,
+		badges
+	};
 	if (lifecycleAction === "shutting-down") return {
 		label: "shutting down",
 		tone: "warning",
@@ -11764,6 +11772,7 @@ function toneToColor(tone) {
 function statusDotColor(agent, now) {
 	if (!agent) return "bg-zinc-500 opacity-50";
 	if (agent.status === "offline") return "bg-zinc-500 opacity-50";
+	if (typeof agent.meta?.lifecycleAction === "string" && agent.meta.lifecycleAction.startsWith("finalizing-")) return "bg-amber-500 animate-pulse";
 	if (agent.meta?.lifecycleAction === "shutting-down" || agent.meta?.lifecycleAction === "restarting") return "bg-yellow-500 animate-pulse";
 	if (agent.meta?.lifecycleAction === "killing") return "bg-red-500 animate-pulse";
 	if (providerBlockedState(agent)) return "bg-red-500 animate-pulse";
@@ -77597,6 +77606,49 @@ function OverviewView() {
 	});
 }
 //#endregion
+//#region src/hooks/use-agent-terminal.ts
+/**
+* Open/close lifecycle for an agent's terminal session. Shared by the agent
+* card and the chat header — both POST a terminal-session, track the target,
+* and DELETE guest sessions on close. Pass null/undefined to no-op (e.g. when
+* no agent is selected).
+*/
+function useAgentTerminal(agentId) {
+	const showError = useRelayStore((s) => s.showError);
+	const [terminalOpen, setTerminalOpen] = (0, import_react.useState)(false);
+	const [terminalTarget, setTerminalTarget] = (0, import_react.useState)(null);
+	const [terminalOpening, setTerminalOpening] = (0, import_react.useState)(false);
+	async function openTerminal() {
+		if (!agentId || terminalOpening) return;
+		setTerminalOpening(true);
+		try {
+			setTerminalTarget(await api("POST", "/agents/" + encodeURIComponent(agentId) + "/terminal-session"));
+			setTerminalOpen(true);
+		} catch (e) {
+			showError("Terminal Failed", e.message);
+		} finally {
+			setTerminalOpening(false);
+		}
+	}
+	function closeTerminal(open) {
+		if (open) {
+			setTerminalOpen(true);
+			return;
+		}
+		setTerminalOpen(false);
+		const target = terminalTarget;
+		setTerminalTarget(null);
+		if (agentId && target?.mode === "guest") api("DELETE", "/agents/" + encodeURIComponent(agentId) + "/terminal-session/" + encodeURIComponent(target.session)).catch(() => {});
+	}
+	return {
+		terminalOpen,
+		terminalTarget,
+		terminalOpening,
+		openTerminal,
+		closeTerminal
+	};
+}
+//#endregion
 //#region node_modules/comma-separated-tokens/index.js
 /**
 * Serialize an array of strings or numbers to comma-separated tokens.
@@ -127279,9 +127331,6 @@ function ChatPanel({ threads, onBack, showBackButton }) {
 	const pendingAttachmentsRef = (0, import_react.useRef)([]);
 	const [pendingAttachments, setPendingAttachments] = (0, import_react.useState)([]);
 	const [dragActive, setDragActive] = (0, import_react.useState)(false);
-	const [terminalOpen, setTerminalOpen] = (0, import_react.useState)(false);
-	const [terminalTarget, setTerminalTarget] = (0, import_react.useState)(null);
-	const [terminalOpening, setTerminalOpening] = (0, import_react.useState)(false);
 	const [filePreview, setFilePreview] = (0, import_react.useState)(null);
 	const [floatingPreview, setFloatingPreview] = (0, import_react.useState)(null);
 	const [filePreviewError, setFilePreviewError] = (0, import_react.useState)("");
@@ -127302,6 +127351,8 @@ function ChatPanel({ threads, onBack, showBackButton }) {
 		selectedInboxThread
 	]);
 	const agent = agentsById[selectedInboxThread] || null;
+	const agentFinalizing = typeof agent?.meta?.lifecycleAction === "string" && agent.meta.lifecycleAction.startsWith("finalizing-");
+	const { terminalOpen, terminalTarget, terminalOpening, openTerminal: handleOpenTerminal, closeTerminal: handleCloseTerminal } = useAgentTerminal(agent?.id);
 	const agentSpawnRequestId = typeof agent?.meta?.spawnRequestId === "string" ? agent.meta.spawnRequestId : "";
 	const importedHistory = (0, import_react.useMemo)(() => {
 		return chatHistoryImports.filter((history) => history.targetAgentId === selectedInboxThread || Boolean(agentSpawnRequestId && history.targetSpawnRequestId === agentSpawnRequestId));
@@ -127382,18 +127433,6 @@ function ChatPanel({ threads, onBack, showBackButton }) {
 		agent?.createdAt,
 		importedHistory
 	]);
-	async function handleOpenTerminal() {
-		if (!agent || terminalOpening) return;
-		setTerminalOpening(true);
-		try {
-			setTerminalTarget(await api("POST", "/agents/" + encodeURIComponent(agent.id) + "/terminal-session"));
-			setTerminalOpen(true);
-		} catch (e) {
-			showError("Terminal Failed", e.message);
-		} finally {
-			setTerminalOpening(false);
-		}
-	}
 	const clearFilePreviewCloseTimer = (0, import_react.useCallback)(() => {
 		if (filePreviewCloseTimer.current === null) return;
 		window.clearTimeout(filePreviewCloseTimer.current);
@@ -127475,16 +127514,6 @@ function ChatPanel({ threads, onBack, showBackButton }) {
 		setFilePreview(null);
 		setFilePreviewError("");
 	}
-	function handleCloseTerminal(open) {
-		if (open) {
-			setTerminalOpen(true);
-			return;
-		}
-		setTerminalOpen(false);
-		const target = terminalTarget;
-		setTerminalTarget(null);
-		if (agent && target?.mode === "guest") api("DELETE", "/agents/" + encodeURIComponent(agent.id) + "/terminal-session/" + encodeURIComponent(target.session)).catch(() => {});
-	}
 	async function uploadFiles(files) {
 		const list = Array.from(files).filter((file) => file.size > 0);
 		if (!list.length) return;
@@ -127530,7 +127559,7 @@ function ChatPanel({ threads, onBack, showBackButton }) {
 		setPendingAttachments([]);
 	}
 	function handleSend() {
-		if (!draft.trim() && readyAttachments.length === 0 || !selectedInboxThread || chatSending || hasPendingUploads) return;
+		if (!draft.trim() && readyAttachments.length === 0 || !selectedInboxThread || chatSending || hasPendingUploads || agentFinalizing) return;
 		const attachments = readyAttachments.map((item) => ({
 			artifactId: item.artifact.id,
 			kind: item.artifact.kind,
@@ -127988,7 +128017,7 @@ function ChatPanel({ threads, onBack, showBackButton }) {
 									}),
 									/* @__PURE__ */ (0, import_jsx_runtime.jsx)(Button, {
 										size: "icon",
-										disabled: !draft.trim() && readyAttachments.length === 0 || hasPendingUploads || chatSending,
+										disabled: !draft.trim() && readyAttachments.length === 0 || hasPendingUploads || chatSending || agentFinalizing,
 										onClick: handleSend,
 										className: "shrink-0 mb-0.5 rounded-xl h-[42px] w-[42px]",
 										children: /* @__PURE__ */ (0, import_jsx_runtime.jsx)(Send, { className: "w-4 h-4" })
@@ -128038,7 +128067,7 @@ function ChatPanel({ threads, onBack, showBackButton }) {
 										})]
 									}), /* @__PURE__ */ (0, import_jsx_runtime.jsx)(Button, {
 										size: "icon",
-										disabled: !draft.trim() && readyAttachments.length === 0 || hasPendingUploads || chatSending,
+										disabled: !draft.trim() && readyAttachments.length === 0 || hasPendingUploads || chatSending || agentFinalizing,
 										onClick: handleSend,
 										className: "rounded-xl h-9 w-9",
 										children: /* @__PURE__ */ (0, import_jsx_runtime.jsx)(Send, { className: "w-4 h-4" })
@@ -128047,7 +128076,7 @@ function ChatPanel({ threads, onBack, showBackButton }) {
 							}),
 							/* @__PURE__ */ (0, import_jsx_runtime.jsx)("p", {
 								className: "text-xs text-muted-foreground mt-1.5 hidden md:block",
-								children: "Enter to send · Shift+Enter for newline"
+								children: agentFinalizing ? `${agent ? displayName(agent) : "Agent"} is wrapping up (${(agent?.meta?.lifecycleAction).slice(11)}) — messaging paused` : "Enter to send · Shift+Enter for newline"
 							})
 						]
 					})
@@ -128176,13 +128205,10 @@ function AgentCard({ agent }) {
 	const openPairInvite = useRelayStore((s) => s.openPairInvite);
 	const openRename = useRelayStore((s) => s.openRename);
 	const openConfirm = useRelayStore((s) => s.openConfirm);
-	const showError = useRelayStore((s) => s.showError);
 	const doAgentAction = useRelayStore((s) => s.doAgentAction);
 	const doDeleteAgent = useRelayStore((s) => s.doDeleteAgent);
 	const openFilesForAgent = useRelayStore((s) => s.openFilesForAgent);
-	const [terminalOpen, setTerminalOpen] = (0, import_react.useState)(false);
-	const [terminalTarget, setTerminalTarget] = (0, import_react.useState)(null);
-	const [terminalOpening, setTerminalOpening] = (0, import_react.useState)(false);
+	const { terminalOpen, terminalTarget, terminalOpening, openTerminal: handleOpenTerminal, closeTerminal: handleCloseTerminal } = useAgentTerminal(agent.id);
 	const pairsMap = usePairsByAgentId();
 	const rawAttention = useAgentAttention(agent);
 	const pair = pairsMap[agent.id] || null;
@@ -128196,28 +128222,6 @@ function AgentCard({ agent }) {
 	const canOpenTerminal = Boolean(agent.providerCapabilities?.terminal?.live?.read || agent.providerCapabilities?.terminal?.attach?.create);
 	const canWriteTerminal = Boolean(agent.providerCapabilities?.terminal?.live?.write || agent.providerCapabilities?.model?.provider === "claude");
 	const canForget = agentCanBeForgotten(agent);
-	async function handleOpenTerminal() {
-		if (terminalOpening) return;
-		setTerminalOpening(true);
-		try {
-			setTerminalTarget(await api("POST", "/agents/" + encodeURIComponent(agent.id) + "/terminal-session"));
-			setTerminalOpen(true);
-		} catch (e) {
-			showError("Terminal Failed", e.message);
-		} finally {
-			setTerminalOpening(false);
-		}
-	}
-	function handleCloseTerminal(open) {
-		if (open) {
-			setTerminalOpen(true);
-			return;
-		}
-		setTerminalOpen(false);
-		const target = terminalTarget;
-		setTerminalTarget(null);
-		if (target?.mode === "guest") api("DELETE", "/agents/" + encodeURIComponent(agent.id) + "/terminal-session/" + encodeURIComponent(target.session)).catch(() => {});
-	}
 	return /* @__PURE__ */ (0, import_jsx_runtime.jsxs)(import_jsx_runtime.Fragment, { children: [/* @__PURE__ */ (0, import_jsx_runtime.jsx)(Card, {
 		className: "group hover:border-zinc-600 transition-colors cursor-pointer",
 		onClick: () => openAgentDetail(agent),

package/runner/src/adapter.ts

@@ -1,5 +1,6 @@
 import type { AgentProfile, Message } from "agent-relay-sdk";
 import { isRecord } from "agent-relay-sdk";
+import type { SessionEvent } from "./session-insights";
 
 export type SemanticStatus = "idle" | "busy" | "offline" | "error";
 type ProviderWorkKind = "provider-turn" | "subagent";
@@ -133,6 +134,15 @@ export interface ProviderAdapter {
   shutdown(process: ManagedProcess, opts: { graceful: boolean; timeoutMs: number }): Promise<void>;
   compact?(process: ManagedProcess): Promise<Record<string, unknown> | void>;
   clearContext?(process: ManagedProcess): Promise<Record<string, unknown> | void>;
+  // Normalize the session so far into the provider-agnostic SessionEvent stream the
+  // Insights context-ratio signal (#183/#184) reduces. Called by the runner's
+  // pre-session-destroy seam before any compact/clear/restart/shutdown. The runner owns
+  // the per-segment cursor (it slices events since the last capture), so this returns the
+  // full ordered event list for the current process lifetime. `ctx.transcriptPath` is
+  // supplied for transcript-backed providers (Claude); event-stream providers (Codex)
+  // ignore it and return their accumulated log. Return null when there is nothing to
+  // measure. Best-effort: may be omitted by providers without a session view yet.
+  collectSessionEvents?(process: ManagedProcess, ctx: { transcriptPath?: string }): Promise<SessionEvent[] | null>;
   // Interrupt the in-flight turn without ending the session (ESC for Claude's
   // tmux pane, turn/interrupt for the Codex app-server). Provider-independent at
   // the runner boundary; each adapter does what its provider actually supports.

package/src/connectors.ts

@@ -243,10 +243,46 @@ async function refreshConnectorStatus(id: string): Promise<void> {
 }
 
 export function startConnectorStatusPoller(): void {
-  void refreshAllConnectorStatuses();
+  // Relaunch connectors that were running before this process restarted (e.g. a
+  // deploy that took down the relay/orchestrator tree) BEFORE the first status
+  // poll overwrites their persisted "running" flag with the now-dead reality.
+  void reconcileConnectorsOnBoot().finally(() => void refreshAllConnectorStatuses());
   setInterval(() => void refreshAllConnectorStatuses(), STATUS_POLL_INTERVAL_MS);
 }
 
+// On boot, bring back any connector whose last persisted state says it was
+// running. `start` is idempotent — a daemon that survived the restart reports
+// "already running"; one that died with the process tree is relaunched. A
+// connector the operator deliberately stopped has running:false persisted, so
+// it stays down. Best-effort: failures are swallowed; the poll reflects truth.
+export async function reconcileConnectorsOnBoot(): Promise<void> {
+  for (const connector of listConnectors()) {
+    const wasRunning = connector.state?.running === true;
+    const canStart = Boolean(connector.manifest.commands.start?.length);
+    if (!wasRunning || !canStart) continue;
+    try {
+      await runConnectorAction(connector.id, "start");
+    } catch { /* boot relaunch is best-effort; status poll will surface failures */ }
+  }
+}
+
+// Flip a connector to running:false when the relay proves its advertised
+// endpoint is unreachable (e.g. the daemon died but state.json still claims
+// running:true). Stops the dashboard from lying until the 60s status poll runs.
+export function markConnectorUnreachable(id: string, detail: string): void {
+  const path = join(connectorDir(id), "state.json");
+  const current = readRecordFile(path);
+  if (!current || current.running === false) return;
+  const next = {
+    ...current,
+    status: "error",
+    detail,
+    running: false,
+    updatedAt: new Date().toISOString(),
+  };
+  writeFileSync(path, JSON.stringify(next, null, 2) + "\n", { mode: 0o600 });
+}
+
 async function refreshAllConnectorStatuses(): Promise<void> {
   for (const connector of listConnectors()) {
     try {

package/src/lifecycle-manager.ts

@@ -268,6 +268,7 @@ export class LifecycleManager {
         graceful,
         timeoutMs: 10_000,
         reason,
+        orchestratorId: orch.id,
         requestedBy: "lifecycle-manager",
         requestedAt: this.now(),
       },

package/src/managed-policy.ts

@@ -32,6 +32,7 @@ export function buildManagedSpawnParams(policy: SpawnPolicy, requestId: string,
   const grant = spawnGrantForProfile(policy.profile);
   return buildSpawnCommand({
     provider: policy.provider,
+    orchestratorId: policy.orchestratorId,
     cwd: policy.cwd,
     workspaceMode: effectiveManagedPolicyWorkspaceMode(policy),
     rig: policy.rig || undefined,

package/src/mcp.ts

@@ -515,11 +515,14 @@ function senderIdentity(auth: McpAuthContext): string | undefined {
   return agents?.length === 1 ? agents[0] : undefined;
 }
 
-// Caller's own agent id for spawn/shutdown gating (#221). `senderIdentity` covers
+// THE caller-identity resolver: the agent id behind this token, for `from`-autofill,
+// relay_whoami, and spawn/shutdown gating (#221, #243). `senderIdentity` covers
 // identity-bearing tokens (interactive/mcp, constraints.agents). Managed agents spawned by
 // the orchestrator authenticate with a runner token that carries no `agents` constraint but
-// DOES carry its spawnRequestId/policy — resolve those back to the registered agent card.
-// Returns undefined for server/admin tokens (unrestricted by design).
+// DOES carry its spawnRequestId/policy — resolve those back to the registered agent card so
+// they never need to pass `from`. Returns undefined for server/admin tokens (unrestricted by
+// design) and multi-agent tokens. Keep `resolveSender`/`relayWhoami` on THIS, not the narrower
+// `senderIdentity`, or managed agents silently lose implicit identity again (the #243 drift).
 function callerAgentId(auth: McpAuthContext): string | undefined {
   const direct = senderIdentity(auth);
   if (direct) return direct;
@@ -536,14 +539,15 @@ function callerAgentId(auth: McpAuthContext): string | undefined {
 
 function resolveSender(auth: McpAuthContext, rawFrom: unknown): string {
   // Token identity wins and cannot be spoofed; any provided `from` is ignored when known.
-  const identity = senderIdentity(auth);
+  // Resolves both constraints.agents tokens AND spawn/policy-managed agents (#243).
+  const identity = callerAgentId(auth);
   if (identity) return identity;
   // Server/integration/multi-agent tokens carry no single identity — keep requiring `from`.
   return stringField(rawFrom, "from", { required: true, max: 200 });
 }
 
 function relayWhoami(auth: McpAuthContext): Record<string, unknown> {
-  const agentId = senderIdentity(auth);
+  const agentId = callerAgentId(auth);
   const agent = agentId ? getAgent(agentId) : null;
   return {
     agentId: agentId ?? null,

package/src/memory-broker-base.ts

@@ -0,0 +1,161 @@
+import type {
+  ActiveMemoryClearReason,
+  ContextPackage,
+  ContextPackageRequest,
+  CreateMemoryInput,
+  Memory,
+  MemoryBrokerCapabilities,
+  MemoryBrokerContext,
+  MemoryQuery,
+  MemorySearchResult,
+  MemoryStats,
+  UpdateMemoryInput,
+} from "./types";
+import type { MemoryBroker } from "./memory-broker-contract";
+import {
+  MemoryBrokerContractError,
+  normalizeMemory,
+  normalizeMemoryBrokerCapabilities,
+  normalizeMemorySearchResult,
+} from "./memory-broker-contract";
+import { isRecord } from "agent-relay-sdk";
+
+export const DEFAULT_MEMORY_BROKER_TIMEOUT_MS = 10_000;
+
+/**
+ * Shared scaffolding for transport-backed memory brokers. The command and HTTP
+ * brokers differ only in how a single request is dispatched — everything else
+ * (operation methods, response normalization, error/result unwrapping) is
+ * identical. Subclasses implement {@link call} and supply a {@link label} used
+ * in error messages.
+ */
+export abstract class AbstractMemoryBroker implements MemoryBroker {
+  /** Human-readable transport name, e.g. "command" or "http". */
+  protected abstract readonly label: string;
+
+  /** Dispatch a single broker operation and return its raw (un-unwrapped) result. */
+  protected abstract call(operation: string, payload: Record<string, unknown>): Promise<unknown>;
+
+  async capabilities(): Promise<MemoryBrokerCapabilities> {
+    return normalizeMemoryBrokerCapabilities(await this.call("capabilities", {}));
+  }
+
+  async create(input: CreateMemoryInput, ctx: MemoryBrokerContext): Promise<Memory> {
+    return normalizeMemory(await this.call("create", { input, ctx }), { now: ctx.now });
+  }
+
+  async get(id: string, ctx: MemoryBrokerContext): Promise<Memory | null> {
+    const value = await this.call("get", { id, ctx });
+    return value === null ? null : normalizeMemory(value, { now: ctx.now });
+  }
+
+  async search(query: MemoryQuery, ctx: MemoryBrokerContext): Promise<MemorySearchResult> {
+    return normalizeMemorySearchResult(await this.call("search", { query, ctx }), { now: ctx.now });
+  }
+
+  async update(id: string, patch: UpdateMemoryInput, ctx: MemoryBrokerContext): Promise<Memory> {
+    return normalizeMemory(await this.call("update", { id, patch, ctx }), { now: ctx.now });
+  }
+
+  async delete(id: string, ctx: MemoryBrokerContext): Promise<void> {
+    await this.call("delete", { id, ctx });
+  }
+
+  async stats(ctx: MemoryBrokerContext): Promise<MemoryStats> {
+    return normalizeStats(await this.call("stats", { ctx }));
+  }
+
+  async assemble(request: ContextPackageRequest, ctx: MemoryBrokerContext): Promise<ContextPackage> {
+    return normalizeContextPackage(await this.call("assemble", { request, ctx }), ctx);
+  }
+
+  async markInjected(agentId: string, memoryIds: string[], ctx: MemoryBrokerContext): Promise<void> {
+    await this.call("mark-injected", { agentId, memoryIds, ctx });
+  }
+
+  async clearActive(agentId: string, reason: ActiveMemoryClearReason, ctx: MemoryBrokerContext): Promise<void> {
+    await this.call("clear-active", { agentId, reason, ctx });
+  }
+
+  async listActive(agentId: string, ctx: MemoryBrokerContext): Promise<Memory[]> {
+    return normalizeMemoryList(await this.call("list-active", { agentId, ctx }), ctx);
+  }
+
+  /** Parse a broker response body, treating empty output as null. */
+  protected parseJson(text: string, operation: string): unknown {
+    if (!text.trim()) return null;
+    try {
+      return JSON.parse(text);
+    } catch {
+      throw new MemoryBrokerContractError(`${this.label} memory broker ${operation} returned invalid JSON`);
+    }
+  }
+
+  /**
+   * Resolve a broker payload to its result. A `{ error }` field is treated as a
+   * failure (even on an otherwise-successful transport response), and a
+   * `{ result }` envelope is unwrapped; anything else is returned as-is.
+   */
+  protected unwrapResult(payload: unknown): unknown {
+    if (isRecord(payload) && Object.hasOwn(payload, "error") && typeof payload.error === "string") {
+      throw new MemoryBrokerContractError(`${this.label} memory broker failed: ${payload.error}`);
+    }
+    if (isRecord(payload) && Object.hasOwn(payload, "result")) return payload.result;
+    return payload;
+  }
+}
+
+export function normalizeContextPackage(value: unknown, ctx: MemoryBrokerContext): ContextPackage {
+  const record = requireRecord(value, "context package");
+  const rawMemories = record.memories;
+  if (!Array.isArray(rawMemories)) throw new MemoryBrokerContractError("context package.memories must be an array");
+  return {
+    memories: rawMemories.map((item) => {
+      const packaged = requireRecord(item, "packaged memory");
+      const priority = packaged.priority;
+      if (priority !== 1 && priority !== 2 && priority !== 3) throw new MemoryBrokerContractError("packaged memory.priority must be 1, 2, or 3");
+      return {
+        memory: normalizeMemory(packaged.memory, { now: ctx.now }),
+        reason: typeof packaged.reason === "string" ? packaged.reason : "broker selected",
+        priority,
+        score: typeof packaged.score === "number" && Number.isFinite(packaged.score) ? packaged.score : undefined,
+      };
+    }),
+    estimatedTokens: typeof record.estimatedTokens === "number" && Number.isFinite(record.estimatedTokens) ? record.estimatedTokens : 0,
+    rolePrompt: typeof record.rolePrompt === "string" ? record.rolePrompt : undefined,
+    recentContext: typeof record.recentContext === "string" ? record.recentContext : undefined,
+  };
+}
+
+function normalizeMemoryList(value: unknown, ctx: MemoryBrokerContext): Memory[] {
+  if (Array.isArray(value)) return value.map((item) => normalizeMemory(item, { now: ctx.now }));
+  if (isRecord(value) && Array.isArray(value.memories)) return value.memories.map((item) => normalizeMemory(item, { now: ctx.now }));
+  throw new MemoryBrokerContractError("memory list-active result must be an array or object with memories array");
+}
+
+function normalizeStats(value: unknown): MemoryStats {
+  const record = requireRecord(value, "memory stats");
+  return {
+    total: numberField(record.total, "memory stats.total"),
+    byType: objectField(record.byType, "memory stats.byType"),
+    byScope: objectField(record.byScope, "memory stats.byScope"),
+    bySensitivity: objectField(record.bySensitivity, "memory stats.bySensitivity"),
+  } as MemoryStats;
+}
+
+function objectField(value: unknown, field: string): Record<string, number> {
+  const record = requireRecord(value, field);
+  const out: Record<string, number> = {};
+  for (const [key, count] of Object.entries(record)) out[key] = numberField(count, `${field}.${key}`);
+  return out;
+}
+
+function numberField(value: unknown, field: string): number {
+  if (typeof value !== "number" || !Number.isFinite(value)) throw new MemoryBrokerContractError(`${field} must be a number`);
+  return value;
+}
+
+function requireRecord(value: unknown, field: string): Record<string, unknown> {
+  if (!isRecord(value)) throw new MemoryBrokerContractError(`${field} must be an object`);
+  return value;
+}

package/src/memory-command-broker.ts

@@ -1,82 +1,18 @@
-import type {
-  ActiveMemoryClearReason,
-  CommandMemoryBrokerConfig,
-  ContextPackage,
-  ContextPackageRequest,
-  CreateMemoryInput,
-  Memory,
-  MemoryBrokerCapabilities,
-  MemoryBrokerContext,
-  MemoryQuery,
-  MemorySearchResult,
-  MemoryStats,
-  UpdateMemoryInput,
-} from "./types";
-import type { MemoryBroker } from "./memory-broker-contract";
-import {
-  MemoryBrokerContractError,
-  normalizeMemory,
-  normalizeMemoryBrokerCapabilities,
-  normalizeMemorySearchResult,
-} from "./memory-broker-contract";
-import { normalizeContextPackage } from "./memory-http-broker";
-import { errMessage, isRecord } from "agent-relay-sdk";
+import type { CommandMemoryBrokerConfig } from "./types";
+import { MemoryBrokerContractError } from "./memory-broker-contract";
+import { AbstractMemoryBroker, DEFAULT_MEMORY_BROKER_TIMEOUT_MS } from "./memory-broker-base";
+import { errMessage } from "agent-relay-sdk";
 
-const DEFAULT_TIMEOUT_MS = 10_000;
-
-export class CommandMemoryBroker implements MemoryBroker {
+export class CommandMemoryBroker extends AbstractMemoryBroker {
+  protected readonly label = "command";
   private readonly timeoutMs: number;
 
   constructor(private readonly config: CommandMemoryBrokerConfig) {
-    this.timeoutMs = config.timeoutMs ?? DEFAULT_TIMEOUT_MS;
-  }
-
-  async capabilities(): Promise<MemoryBrokerCapabilities> {
-    return normalizeMemoryBrokerCapabilities(await this.call("capabilities", {}));
-  }
-
-  async create(input: CreateMemoryInput, ctx: MemoryBrokerContext): Promise<Memory> {
-    return normalizeMemory(await this.call("create", { input, ctx }), { now: ctx.now });
-  }
-
-  async get(id: string, ctx: MemoryBrokerContext): Promise<Memory | null> {
-    const value = await this.call("get", { id, ctx });
-    return value === null ? null : normalizeMemory(value, { now: ctx.now });
-  }
-
-  async search(query: MemoryQuery, ctx: MemoryBrokerContext): Promise<MemorySearchResult> {
-    return normalizeMemorySearchResult(await this.call("search", { query, ctx }), { now: ctx.now });
-  }
-
-  async update(id: string, patch: UpdateMemoryInput, ctx: MemoryBrokerContext): Promise<Memory> {
-    return normalizeMemory(await this.call("update", { id, patch, ctx }), { now: ctx.now });
-  }
-
-  async delete(id: string, ctx: MemoryBrokerContext): Promise<void> {
-    await this.call("delete", { id, ctx });
-  }
-
-  async stats(ctx: MemoryBrokerContext): Promise<MemoryStats> {
-    return normalizeStats(await this.call("stats", { ctx }));
-  }
-
-  async assemble(request: ContextPackageRequest, ctx: MemoryBrokerContext): Promise<ContextPackage> {
-    return normalizeContextPackage(await this.call("assemble", { request, ctx }), ctx);
-  }
-
-  async markInjected(agentId: string, memoryIds: string[], ctx: MemoryBrokerContext): Promise<void> {
-    await this.call("mark-injected", { agentId, memoryIds, ctx });
+    super();
+    this.timeoutMs = config.timeoutMs ?? DEFAULT_MEMORY_BROKER_TIMEOUT_MS;
   }
 
-  async clearActive(agentId: string, reason: ActiveMemoryClearReason, ctx: MemoryBrokerContext): Promise<void> {
-    await this.call("clear-active", { agentId, reason, ctx });
-  }
-
-  async listActive(agentId: string, ctx: MemoryBrokerContext): Promise<Memory[]> {
-    return normalizeMemoryList(await this.call("list-active", { agentId, ctx }), ctx);
-  }
-
-  private async call(operation: string, payload: Record<string, unknown>): Promise<unknown> {
+  protected async call(operation: string, payload: Record<string, unknown>): Promise<unknown> {
     const proc = Bun.spawn([this.config.command, ...(this.config.args ?? [])], {
       stdin: "pipe",
       stdout: "pipe",
@@ -102,7 +38,7 @@ export class CommandMemoryBroker implements MemoryBroker {
       if (exitCode !== 0) {
         throw new MemoryBrokerContractError(`command memory broker ${operation} failed: exit ${exitCode}${stderr.trim() ? ` ${stderr.trim()}` : ""}`);
       }
-      return unwrapResult(parseJson(stdout, operation));
+      return this.unwrapResult(this.parseJson(stdout, operation));
     } catch (error) {
       if (error instanceof MemoryBrokerContractError) throw error;
       throw new MemoryBrokerContractError(`command memory broker ${operation} failed: ${errMessage(error)}`);
@@ -111,48 +47,3 @@ export class CommandMemoryBroker implements MemoryBroker {
     }
   }
 }
-
-function parseJson(text: string, operation: string): unknown {
-  if (!text.trim()) return null;
-  try {
-    return JSON.parse(text);
-  } catch {
-    throw new MemoryBrokerContractError(`command memory broker ${operation} returned invalid JSON`);
-  }
-}
-
-function unwrapResult(payload: unknown): unknown {
-  if (isRecord(payload) && Object.hasOwn(payload, "error") && typeof payload.error === "string") {
-    throw new MemoryBrokerContractError(`command memory broker failed: ${payload.error}`);
-  }
-  if (isRecord(payload) && Object.hasOwn(payload, "result")) return payload.result;
-  return payload;
-}
-
-function normalizeMemoryList(value: unknown, ctx: MemoryBrokerContext): Memory[] {
-  if (Array.isArray(value)) return value.map((item) => normalizeMemory(item, { now: ctx.now }));
-  if (isRecord(value) && Array.isArray(value.memories)) return value.memories.map((item) => normalizeMemory(item, { now: ctx.now }));
-  throw new MemoryBrokerContractError("memory list-active result must be an array or object with memories array");
-}
-
-function normalizeStats(value: unknown): MemoryStats {
-  if (!isRecord(value)) throw new MemoryBrokerContractError("memory stats must be an object");
-  return {
-    total: numberField(value.total, "memory stats.total"),
-    byType: objectField(value.byType, "memory stats.byType"),
-    byScope: objectField(value.byScope, "memory stats.byScope"),
-    bySensitivity: objectField(value.bySensitivity, "memory stats.bySensitivity"),
-  } as MemoryStats;
-}
-
-function objectField(value: unknown, field: string): Record<string, number> {
-  if (!isRecord(value)) throw new MemoryBrokerContractError(`${field} must be an object`);
-  const out: Record<string, number> = {};
-  for (const [key, count] of Object.entries(value)) out[key] = numberField(count, `${field}.${key}`);
-  return out;
-}
-
-function numberField(value: unknown, field: string): number {
-  if (typeof value !== "number" || !Number.isFinite(value)) throw new MemoryBrokerContractError(`${field} must be a number`);
-  return value;
-}

package/src/memory-http-broker.ts

@@ -1,83 +1,22 @@
-import type {
-  ActiveMemoryClearReason,
-  ContextPackage,
-  ContextPackageRequest,
-  CreateMemoryInput,
-  HttpMemoryBrokerConfig,
-  Memory,
-  MemoryBrokerCapabilities,
-  MemoryBrokerContext,
-  MemoryQuery,
-  MemorySearchResult,
-  MemoryStats,
-  UpdateMemoryInput,
-} from "./types";
-import type { MemoryBroker } from "./memory-broker-contract";
-import {
-  MemoryBrokerContractError,
-  normalizeMemory,
-  normalizeMemoryBrokerCapabilities,
-  normalizeMemorySearchResult,
-} from "./memory-broker-contract";
+import type { HttpMemoryBrokerConfig } from "./types";
+import { MemoryBrokerContractError } from "./memory-broker-contract";
+import { AbstractMemoryBroker, DEFAULT_MEMORY_BROKER_TIMEOUT_MS } from "./memory-broker-base";
 import { errMessage, isRecord } from "agent-relay-sdk";
 
-const DEFAULT_TIMEOUT_MS = 10_000;
+export { normalizeContextPackage } from "./memory-broker-base";
 
-export class HttpMemoryBroker implements MemoryBroker {
+export class HttpMemoryBroker extends AbstractMemoryBroker {
+  protected readonly label = "http";
   private readonly baseUrl: string;
   private readonly timeoutMs: number;
 
   constructor(private readonly config: HttpMemoryBrokerConfig) {
+    super();
     this.baseUrl = config.url.replace(/\/+$/, "");
-    this.timeoutMs = config.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    this.timeoutMs = config.timeoutMs ?? DEFAULT_MEMORY_BROKER_TIMEOUT_MS;
   }
 
-  async capabilities(): Promise<MemoryBrokerCapabilities> {
-    return normalizeMemoryBrokerCapabilities(await this.call("capabilities", {}));
-  }
-
-  async create(input: CreateMemoryInput, ctx: MemoryBrokerContext): Promise<Memory> {
-    return normalizeMemory(await this.call("create", { input, ctx }), { now: ctx.now });
-  }
-
-  async get(id: string, ctx: MemoryBrokerContext): Promise<Memory | null> {
-    const value = await this.call("get", { id, ctx });
-    return value === null ? null : normalizeMemory(value, { now: ctx.now });
-  }
-
-  async search(query: MemoryQuery, ctx: MemoryBrokerContext): Promise<MemorySearchResult> {
-    return normalizeMemorySearchResult(await this.call("search", { query, ctx }), { now: ctx.now });
-  }
-
-  async update(id: string, patch: UpdateMemoryInput, ctx: MemoryBrokerContext): Promise<Memory> {
-    return normalizeMemory(await this.call("update", { id, patch, ctx }), { now: ctx.now });
-  }
-
-  async delete(id: string, ctx: MemoryBrokerContext): Promise<void> {
-    await this.call("delete", { id, ctx });
-  }
-
-  async stats(ctx: MemoryBrokerContext): Promise<MemoryStats> {
-    return normalizeStats(await this.call("stats", { ctx }));
-  }
-
-  async assemble(request: ContextPackageRequest, ctx: MemoryBrokerContext): Promise<ContextPackage> {
-    return normalizeContextPackage(await this.call("assemble", { request, ctx }), ctx);
-  }
-
-  async markInjected(agentId: string, memoryIds: string[], ctx: MemoryBrokerContext): Promise<void> {
-    await this.call("mark-injected", { agentId, memoryIds, ctx });
-  }
-
-  async clearActive(agentId: string, reason: ActiveMemoryClearReason, ctx: MemoryBrokerContext): Promise<void> {
-    await this.call("clear-active", { agentId, reason, ctx });
-  }
-
-  async listActive(agentId: string, ctx: MemoryBrokerContext): Promise<Memory[]> {
-    return normalizeMemoryList(await this.call("list-active", { agentId, ctx }), ctx);
-  }
-
-  private async call(operation: string, body: Record<string, unknown>): Promise<unknown> {
+  protected async call(operation: string, body: Record<string, unknown>): Promise<unknown> {
     const controller = new AbortController();
     const timer = setTimeout(() => controller.abort(), this.timeoutMs);
     try {
@@ -88,12 +27,12 @@ export class HttpMemoryBroker implements MemoryBroker {
         signal: controller.signal,
       });
       const text = await res.text();
-      const payload = parseJson(text, operation);
+      const payload = this.parseJson(text, operation);
       if (!res.ok) {
         const detail = isRecord(payload) && typeof payload.error === "string" ? payload.error : text.trim();
         throw new MemoryBrokerContractError(`http memory broker ${operation} failed: ${res.status}${detail ? ` ${detail}` : ""}`);
       }
-      return unwrapResult(payload);
+      return this.unwrapResult(payload);
     } catch (error) {
       if (error instanceof MemoryBrokerContractError) throw error;
       if (error instanceof DOMException && error.name === "AbortError") {
@@ -114,72 +53,3 @@ export class HttpMemoryBroker implements MemoryBroker {
     return headers;
   }
 }
-
-function parseJson(text: string, operation: string): unknown {
-  if (!text.trim()) return null;
-  try {
-    return JSON.parse(text);
-  } catch {
-    throw new MemoryBrokerContractError(`http memory broker ${operation} returned invalid JSON`);
-  }
-}
-
-function unwrapResult(payload: unknown): unknown {
-  if (isRecord(payload) && Object.hasOwn(payload, "result")) return payload.result;
-  return payload;
-}
-
-export function normalizeContextPackage(value: unknown, ctx: MemoryBrokerContext): ContextPackage {
-  const record = requireRecord(value, "context package");
-  const rawMemories = record.memories;
-  if (!Array.isArray(rawMemories)) throw new MemoryBrokerContractError("context package.memories must be an array");
-  return {
-    memories: rawMemories.map((item) => {
-      const packaged = requireRecord(item, "packaged memory");
-      const priority = packaged.priority;
-      if (priority !== 1 && priority !== 2 && priority !== 3) throw new MemoryBrokerContractError("packaged memory.priority must be 1, 2, or 3");
-      return {
-        memory: normalizeMemory(packaged.memory, { now: ctx.now }),
-        reason: typeof packaged.reason === "string" ? packaged.reason : "broker selected",
-        priority,
-        score: typeof packaged.score === "number" && Number.isFinite(packaged.score) ? packaged.score : undefined,
-      };
-    }),
-    estimatedTokens: typeof record.estimatedTokens === "number" && Number.isFinite(record.estimatedTokens) ? record.estimatedTokens : 0,
-    rolePrompt: typeof record.rolePrompt === "string" ? record.rolePrompt : undefined,
-    recentContext: typeof record.recentContext === "string" ? record.recentContext : undefined,
-  };
-}
-
-function normalizeMemoryList(value: unknown, ctx: MemoryBrokerContext): Memory[] {
-  if (Array.isArray(value)) return value.map((item) => normalizeMemory(item, { now: ctx.now }));
-  if (isRecord(value) && Array.isArray(value.memories)) return value.memories.map((item) => normalizeMemory(item, { now: ctx.now }));
-  throw new MemoryBrokerContractError("memory list-active result must be an array or object with memories array");
-}
-
-function normalizeStats(value: unknown): MemoryStats {
-  const record = requireRecord(value, "memory stats");
-  return {
-    total: numberField(record.total, "memory stats.total"),
-    byType: objectField(record.byType, "memory stats.byType"),
-    byScope: objectField(record.byScope, "memory stats.byScope"),
-    bySensitivity: objectField(record.bySensitivity, "memory stats.bySensitivity"),
-  } as MemoryStats;
-}
-
-function objectField(value: unknown, field: string): Record<string, number> {
-  const record = requireRecord(value, field);
-  const out: Record<string, number> = {};
-  for (const [key, count] of Object.entries(record)) out[key] = numberField(count, `${field}.${key}`);
-  return out;
-}
-
-function numberField(value: unknown, field: string): number {
-  if (typeof value !== "number" || !Number.isFinite(value)) throw new MemoryBrokerContractError(`${field} must be a number`);
-  return value;
-}
-
-function requireRecord(value: unknown, field: string): Record<string, unknown> {
-  if (!isRecord(value)) throw new MemoryBrokerContractError(`${field} must be an object`);
-  return value;
-}

package/src/routes.ts

@@ -139,6 +139,7 @@ import { createToken, deleteTokenProfile, getToken, getTokenProfile, listTokenPr
 import {
   getConnector,
   listConnectors,
+  markConnectorUnreachable,
   readConnectorConfig,
   registerConnectorManifest,
   runConnectorAction,
@@ -2197,7 +2198,7 @@ function restartSpawnParamsForAgent(
   const policy = policyName ? getSpawnPolicy(policyName) : null;
   const requestedBy = opts.resumeId ? "dashboard-resume" : "dashboard-restart";
   if (policy) {
-    const params = { ...managedSpawnParams(policy.value, requestId), agentId: agent.id, requestedBy };
+    const params = { ...buildManagedSpawnParams(policy.value, requestId, { createdBy: "managed-agent" }), agentId: agent.id, requestedBy };
     return opts.resumeId ? withClaudeResumeParams(params, opts.resumeId, agent.id) : params;
   }
 
@@ -4811,11 +4812,6 @@ function policyStatusPayload(policy: SpawnPolicy) {
   };
 }
 
-function managedSpawnParams(policy: SpawnPolicy, requestId: string): Record<string, unknown> {
-  return buildManagedSpawnParams(policy, requestId, { createdBy: "managed-agent" });
-}
-
-
 function requirePolicyAndOrchestrator(name: string): { policy: SpawnPolicy; orch: NonNullable<ReturnType<typeof getOrchestrator>> } | Response {
   const entry = getSpawnPolicy(name);
   if (!entry) return error("spawn policy not found", 404);
@@ -4861,7 +4857,7 @@ function enqueuePolicyStart(policy: SpawnPolicy, reason: string): Command | Resp
     target: orch.agentId,
     correlationId: requestId,
     params: {
-      ...managedSpawnParams(policy, requestId),
+      ...buildManagedSpawnParams(policy, requestId, { createdBy: "managed-agent" }),
       reason,
       orchestratorId: orch.id,
     },
@@ -4875,7 +4871,7 @@ function enqueuePolicyStop(policy: SpawnPolicy, action: "shutdown" | "restart",
   if (!orch) return error("orchestrator not found", 404);
   const state = getManagedAgentState(policy.name);
   const restartRequestId = action === "restart" ? spawnRequestId() : undefined;
-  const restartSpawn = restartRequestId ? managedSpawnParams(policy, restartRequestId) : undefined;
+  const restartSpawn = restartRequestId ? buildManagedSpawnParams(policy, restartRequestId, { createdBy: "managed-agent" }) : undefined;
   const nextState = upsertManagedAgentState({
     policyName: policy.name,
     status: "stopping",
@@ -5784,6 +5780,13 @@ const postConnectorCall: Handler = async (req, params) => {
       headers: { "content-type": res.headers.get("content-type") || "application/json" },
     });
   } catch (e) {
+    // A connection error (refused/reset/DNS) means the advertised endpoint is
+    // genuinely down — reconcile the stale running:true so the dashboard stops
+    // claiming the connector is healthy. A timeout (AbortError) may just be a
+    // slow daemon, so leave its state alone.
+    if ((e as Error).name !== "AbortError") {
+      markConnectorUnreachable(params.id!, `endpoint unreachable: ${(e as Error).message}`);
+    }
     return error(`failed to reach connector: ${(e as Error).message}`, 502);
   }
 };