agent-relay-server 0.22.0 → 0.24.0

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";
@@ -84,6 +85,9 @@ export interface RunnerSpawnConfig {
   providerConfig: ProviderConfig;
   env: Record<string, string>;
   controlPort: number;
+  // Stage 2 (#215): the MCP endpoint the agent connects to — the runner-local proxy URL when the
+  // proxy is active. Undefined → the adapter targets the relay's MCP endpoint directly (Stage 1).
+  relayMcpEndpoint?: string;
   monitor?: {
     deliver(messages: Message[]): Promise<number[]>;
   };
@@ -130,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;
-}