agent-relay-server 0.17.0 → 0.18.0

package/src/lifecycle-manager.ts

@@ -1,5 +1,5 @@
-import { isAbsolute, relative, resolve } from "node:path";
 import { createCommand } from "./commands-db";
+import { isPathWithinBase } from "./utils";
 import { createActivityEvent, deleteWorkspace, getAgent, getDb, getOrchestrator, listOrchestrators, listWorkspaces, resolveQueuedPolicyMessages } from "./db";
 import {
   getManagedAgentState,
@@ -8,7 +8,9 @@ import {
   upsertManagedAgentState,
 } from "./config-store";
 import { emitRelayEvent } from "./events";
+import { emitCommandEvent } from "./command-events";
 import { buildManagedSpawnParams } from "./managed-policy";
+import { generateSpawnRequestId } from "./spawn-command";
 import type { Command, ManagedAgent, ManagedAgentState, ManagedSessionExitDiagnostics, SpawnPolicy } from "./types";
 
 const DEFAULT_TICK_MS = 10_000;
@@ -208,7 +210,7 @@ export class LifecycleManager {
       this.emitState(state);
       return null;
     }
-    const spawnRequestId = `sp_${crypto.randomUUID()}`;
+    const spawnRequestId = generateSpawnRequestId();
     const state = upsertManagedAgentState({
       policyName: policy.name,
       status: "starting",
@@ -230,7 +232,7 @@ export class LifecycleManager {
         reason,
       },
     });
-    this.emitCommand(command);
+    emitCommandEvent(command, "command.requested");
     return command;
   }
 
@@ -270,7 +272,7 @@ export class LifecycleManager {
         requestedAt: this.now(),
       },
     });
-    this.emitCommand(command);
+    emitCommandEvent(command, "command.requested");
     return command;
   }
 
@@ -278,7 +280,7 @@ export class LifecycleManager {
     const orch = getOrchestrator(policy.orchestratorId);
     if (!orch) return null;
     const state = getManagedAgentState(policy.name);
-    const restartRequestId = `sp_${crypto.randomUUID()}`;
+    const restartRequestId = generateSpawnRequestId();
     const restartSpawn = buildManagedSpawnParams(policy, restartRequestId, { createdBy: "lifecycle-manager", requestedAt: this.now() });
     const restarted = upsertManagedAgentState({
       policyName: policy.name,
@@ -314,7 +316,7 @@ export class LifecycleManager {
         requestedAt: this.now(),
       },
     });
-    this.emitCommand(command);
+    emitCommandEvent(command, "command.requested");
     return command;
   }
 
@@ -406,7 +408,7 @@ export class LifecycleManager {
         requestedAt: this.now(),
       },
     });
-    this.emitCommand(command);
+    emitCommandEvent(command, "command.requested");
     return command;
   }
 
@@ -564,15 +566,6 @@ export class LifecycleManager {
     });
   }
 
-  private emitCommand(command: Command): void {
-    emitRelayEvent({
-      type: "command.requested",
-      source: command.source,
-      subject: command.id,
-      data: { command },
-    });
-  }
-
   // When an agent disappears, its isolated worktrees would otherwise sit
   // `active` on disk forever. Dispatch a workspace.reconcile command to the
   // owning orchestrator, which probes the worktree and either removes it (no
@@ -593,7 +586,7 @@ export class LifecycleManager {
     const orchestrators = listOrchestrators();
     for (const ws of candidates) {
       const orch = orchestrators.find(
-        (candidate) => candidate.status === "online" && pathWithinBaseDir(ws.sourceCwd, candidate.baseDir),
+        (candidate) => candidate.status === "online" && isPathWithinBase(ws.sourceCwd, candidate.baseDir),
       );
       if (!orch) continue;
       const command = createCommand({
@@ -614,17 +607,11 @@ export class LifecycleManager {
           requestedAt: this.now(),
         },
       });
-      this.emitCommand(command);
+      emitCommandEvent(command, "command.requested");
     }
   }
 }
 
-function pathWithinBaseDir(path: string | undefined, baseDir: string | undefined): boolean {
-  if (!path || !baseDir) return false;
-  const rel = relative(resolve(baseDir), resolve(path));
-  return rel === "" || (!!rel && !rel.startsWith("..") && !isAbsolute(rel));
-}
-
 let singleton: LifecycleManager | null = null;
 
 export function getLifecycleManager(): LifecycleManager {

package/src/maintenance.ts

@@ -33,6 +33,8 @@ import {
 } from "./db";
 import type { WorkspaceMergePreview, WorkspaceRecord, WorkspaceStatus } from "./types";
 import { requestWorkspaceMerge } from "./workspace-merge";
+import { workspaceActiveClaim } from "./workspace-claim";
+import { RELAY_TOKEN_HEADER } from "agent-relay-sdk";
 import { getStewardConfig } from "./config-store";
 import { ensureRepoSteward } from "./steward";
 import { emitRelayEvent } from "./events";
@@ -392,7 +394,7 @@ const definitions: MaintenanceJobDefinition[] = [
   {
     id: "workspace-auto-merge",
     title: "Workspace auto-merge",
-    description: "Auto-merge clean fast-forward review_requested worktrees into base under the per-repo lease; conflicts and diverged bases are left for the steward.",
+    description: "Auto-merge any non-conflicting review_requested worktree into base under the per-repo lease (rebasing when the base moved on); only real or unknown conflicts are left for the steward.",
     intervalMs: WORKSPACE_AUTO_MERGE_INTERVAL_MS,
     runOnStart: false,
     timeoutMs: 60 * 1000,
@@ -421,7 +423,7 @@ async function fetchHostMergePreview(apiUrl: string, workspace: WorkspaceRecord)
   if (workspace.baseSha) query.set("baseSha", workspace.baseSha);
   const headers: Record<string, string> = {};
   const token = process.env.AGENT_RELAY_TOKEN;
-  if (token) headers["X-Agent-Relay-Token"] = token;
+  if (token) headers[RELAY_TOKEN_HEADER] = token;
   try {
     const res = await fetch(`${apiUrl}/api/workspace/merge-preview?${query.toString()}`, { headers, signal: AbortSignal.timeout(8_000) });
     if (!res.ok) return null;
@@ -535,7 +537,7 @@ function wakeRepoSteward(ws: WorkspaceRecord, reason: string): string | null {
       to: `policy:${policyName}`,
       kind: "system",
       subject: `Steward: ${ws.status} workspace needs attention`,
-      body: `Workspace \`${ws.branch ?? ws.id}\` in ${ws.repoRoot} is ${ws.status} and could not auto-land (${reason}). cd into ${ws.worktreePath}, rebase onto ${ws.baseRef ?? "base"}, resolve, run checks, then land it via POST /api/workspaces/${ws.id}/actions {"action":"merge","strategy":"rebase-ff"} — or escalate if you can't.`,
+      body: `Workspace \`${ws.branch ?? ws.id}\` (id ${ws.id}) in ${ws.repoRoot} is ${ws.status} and could not auto-land (${reason}). Claim it first so auto-merge yields: \`agent-relay workspace claim --id ${ws.id} --purpose steward\`. Inspect: \`agent-relay steward inspect ${ws.id}\`. Then cd into ${ws.worktreePath}, rebase onto ${ws.baseRef ?? "base"}, resolve, run checks, and land: \`agent-relay workspace land --id ${ws.id} --strategy rebase-ff\` — or \`agent-relay workspace release --id ${ws.id}\` and escalate if you can't.`,
       payload: { kind: "workspace.steward-task", workspaceId: ws.id, repoRoot: ws.repoRoot, worktreePath: ws.worktreePath, branch: ws.branch, baseRef: ws.baseRef, status: ws.status, reason },
     });
     emitNewMessage(msg);
@@ -655,14 +657,12 @@ async function scanWorkspaceConflicts(): Promise<Record<string, unknown>> {
   return { scanned: candidates.length, flagged, cleared, merged, notifiedStewards };
 }
 
-// Deterministic auto-land (Layer 0, issue #167). Walk the "ready to land" queue
-// (`review_requested` isolated worktrees) and, for any whose work is a strict
-// clean fast-forward (no conflict, base hasn't moved, real commits ahead), land
-// it via the shared merge helper — the same lease-serialized path the merge route
-// uses. Conflicts and diverged bases (`behind>0`, even if cleanly rebasable) are
-// deliberately left for the steward (a human or, later, the managed steward
-// agent): per the chosen "Clean FF immediate" gate, anything needing a rebase or
-// conflict reasoning is not auto-landed. No agent in the loop for the easy case.
+// Deterministic auto-land (Layer 0, issue #167 / #207). Walk the "ready to land"
+// queue (`review_requested` isolated worktrees) and land any whose merge is
+// predicted conflict-free, via the shared lease-serialized merge helper — even
+// when the base moved on (behind>0): mergeRebaseFf rebases onto the current base
+// before fast-forwarding. Only a predicted conflict or an unknown merge state is
+// left for the steward; clean parallel work lands with no agent in the loop.
 async function autoMergeCleanFastForwards(): Promise<Record<string, unknown>> {
   if (process.env.AGENT_RELAY_WORKSPACE_AUTO_MERGE === "0") return { skipped: "disabled" };
   const orchestrators = listOrchestrators().filter((orch) => orch.status === "online" && orch.apiUrl);
@@ -674,10 +674,13 @@ async function autoMergeCleanFastForwards(): Promise<Record<string, unknown>> {
   const stewardEnabled = getStewardConfig().enabled;
   const merged: string[] = [];
   const heldByLease: string[] = [];
+  const heldByClaim: string[] = [];
   const leftForSteward: string[] = [];
   const wokeStewards: string[] = [];
 
   for (const ws of candidates) {
+    // A claimed workspace is being validated by a steward — don't race it (#208).
+    if (workspaceActiveClaim(ws)) { heldByClaim.push(ws.id); continue; }
     const orch = orchestrators.find((candidate) => workspacePathWithinBase(ws.sourceCwd, candidate.baseDir));
     if (!orch?.apiUrl) continue;
     const preview = await fetchHostMergePreview(orch.apiUrl, ws);
@@ -686,14 +689,17 @@ async function autoMergeCleanFastForwards(): Promise<Record<string, unknown>> {
     if (p.error || p.missing) continue;
 
     const ahead = p.unmergedAhead ?? p.ahead ?? 0;
-    const cleanFF = p.cleanFastForward === true && p.conflict !== true && (p.behind ?? 0) === 0 && ahead > 0;
-    if (!cleanFF) {
-      // Base moved on (behind>0) or conflict — needs reasoning/rebase, which is the
-      // steward's job. Wake the managed steward when enabled (cooldown-guarded);
-      // otherwise leave it for conflict-scan's legacy ping / human review.
+    const behind = p.behind ?? 0;
+    // Land anything that won't conflict — including a base that moved on (behind>0)
+    // but rebases cleanly. The merge-tree prediction already accounts for the moved
+    // base, and mergeRebaseFf rebases then aborts-to-conflict on a real replay
+    // conflict, so a too-optimistic prediction degrades safely to review_requested.
+    // Only a predicted conflict (true) or unknown state (undefined) goes to the steward.
+    const canLand = p.conflict === false && ahead > 0;
+    if (!canLand) {
       leftForSteward.push(ws.id);
       if (stewardEnabled) {
-        const woke = wakeRepoSteward(ws, (p.behind ?? 0) > 0 ? "base moved on (behind>0)" : "conflict");
+        const woke = wakeRepoSteward(ws, p.conflict === true ? "conflict" : "merge state unknown");
         if (woke) wokeStewards.push(woke);
       }
       continue;
@@ -710,8 +716,8 @@ async function autoMergeCleanFastForwards(): Promise<Record<string, unknown>> {
     createActivityEvent({
       clientId: `workspace-auto-merge-${ws.id}-${Date.now()}`,
       kind: "state",
-      title: "Workspace auto-merging (clean fast-forward)",
-      body: `${ws.branch ?? ws.id} → ${p.baseRef ?? "base"} (${ahead} ahead, clean)`,
+      title: behind > 0 ? "Workspace auto-merging (rebase)" : "Workspace auto-merging (clean fast-forward)",
+      body: `${ws.branch ?? ws.id} → ${p.baseRef ?? "base"} (${ahead} ahead${behind > 0 ? `, ${behind} behind — rebasing` : ", clean"})`,
       meta: ws.branch ?? ws.id,
       icon: "ti-git-merge",
       view: "orchestrators",
@@ -719,7 +725,7 @@ async function autoMergeCleanFastForwards(): Promise<Record<string, unknown>> {
     });
   }
 
-  return { scanned: candidates.length, merged, heldByLease, leftForSteward, wokeStewards };
+  return { scanned: candidates.length, merged, heldByLease, heldByClaim, leftForSteward, wokeStewards };
 }
 
 // Send a system DM, swallowing failures (a stale/missing/misconfigured target

package/src/managed-policy.ts

@@ -1,6 +1,6 @@
-import { resolveProviderSelection } from "agent-relay-sdk/provider-catalog";
-import { getAgentProfile, workspaceSpawnParams } from "./config-store";
+import { getAgentProfile } from "./config-store";
 import { runnerRuntimeTokenEnv } from "./runtime-tokens";
+import { buildSpawnCommand, resolveSpawnModelParams } from "./spawn-command";
 import type { SpawnPolicy, WorkspaceMode } from "./types";
 
 export function managedPolicyProviderArgs(policy: SpawnPolicy): string[] {
@@ -20,23 +20,6 @@ export function effectiveManagedPolicyWorkspaceMode(policy: SpawnPolicy): Worksp
   return policy.binding?.type === "channel" ? "shared" : "inherit";
 }
 
-function resolvedModelParams(policy: SpawnPolicy): Record<string, string> {
-  if (!policy.model && !policy.effort) return {};
-  try {
-    const selection = resolveProviderSelection({ provider: policy.provider, model: policy.model, effort: policy.effort });
-    return {
-      ...(selection.modelAlias ? { model: selection.modelAlias } : {}),
-      ...(selection.providerModel ? { providerModel: selection.providerModel } : {}),
-      ...(selection.effort ? { effort: selection.effort } : {}),
-    };
-  } catch {
-    return {
-      ...(policy.model ? { model: policy.model } : {}),
-      ...(policy.effort ? { effort: policy.effort } : {}),
-    };
-  }
-}
-
 export interface ManagedSpawnContext {
   createdBy: string;
   requestedAt?: number;
@@ -46,23 +29,21 @@ export function buildManagedSpawnParams(policy: SpawnPolicy, requestId: string,
   const providerArgs = managedPolicyProviderArgs(policy);
   const prompt = managedPolicyLaunchPrompt(policy);
   const agentProfile = policy.profile ? getAgentProfile(policy.profile)?.value : undefined;
-  return {
-    action: "spawn",
+  return buildSpawnCommand({
     provider: policy.provider,
     cwd: policy.cwd,
     workspaceMode: effectiveManagedPolicyWorkspaceMode(policy),
-    ...(policy.rig ? { rig: policy.rig } : {}),
-    ...resolvedModelParams(policy),
-    ...(policy.profile ? { profile: policy.profile } : {}),
-    ...(agentProfile ? { agentProfile } : {}),
-    ...workspaceSpawnParams(),
+    rig: policy.rig || undefined,
+    modelParams: resolveSpawnModelParams(policy.provider, policy.model, policy.effort, { onError: "passthrough", skipDefaultWhenEmpty: true }),
+    profile: policy.profile || undefined,
+    agentProfile,
     label: policy.label,
     tags: policy.tags,
     capabilities: policy.capabilities,
     approvalMode: policy.permissionMode,
     permissionMode: policy.permissionMode,
     providerArgs,
-    ...(prompt ? { prompt } : {}),
+    prompt: prompt || undefined,
     headless: true,
     policyName: policy.name,
     spawnRequestId: requestId,
@@ -77,5 +58,5 @@ export function buildManagedSpawnParams(policy: SpawnPolicy, requestId: string,
     }),
     requestedBy: ctx.createdBy,
     requestedAt: ctx.requestedAt ?? Date.now(),
-  };
+  });
 }

package/src/mcp.ts

@@ -1,8 +1,8 @@
 import { Buffer } from "node:buffer";
-import { randomUUID } from "node:crypto";
-import { isAbsolute, relative, resolve } from "node:path";
 import { getArtifactStorage, maxArtifactBytes, normalizeDigest } from "./artifact-storage";
 import { createCommand } from "./commands-db";
+import { buildSpawnCommand, generateSpawnRequestId, resolveSpawnModelParams, type SpawnModelParams } from "./spawn-command";
+import { isPathWithinBase } from "./utils";
 import { MAX_BODY_BYTES, VERSION } from "./config";
 import { getManagedAgentState, getSpawnPolicy, listSpawnPolicies } from "./config-store";
 import {
@@ -33,7 +33,8 @@ import {
   isIntegrationAllowed,
 } from "./security";
 import type { ActivityKind, AgentCard, ArtifactKind, ArtifactSensitivity, AttachmentRef, Command, SendMessageInput, Message, SpawnApprovalMode, SpawnProvider } from "./types";
-import { resolveProviderSelection, type ProviderEffort } from "agent-relay-sdk/provider-catalog";
+import { type ProviderEffort } from "agent-relay-sdk/provider-catalog";
+import { isRecord, SPAWN_PROVIDERS, APPROVAL_MODES, VALID_EFFORTS } from "agent-relay-sdk";
 import { childRunnerRuntimeTokenEnv, runnerRuntimeTokenEnv } from "./runtime-tokens";
 
 type JsonRpcId = string | number | null;
@@ -66,9 +67,7 @@ const VALID_ARTIFACT_KINDS = ["image", "audio", "video", "document", "archive",
 const VALID_ARTIFACT_SENSITIVITIES = ["public", "normal", "sensitive", "secret"] as const;
 const VALID_ARTIFACT_ROLES = ["media", "patch", "report", "log", "output", "input"] as const;
 const VALID_ARTIFACT_ENTITY_TYPES = ["message", "task", "recipeRun", "recipeStep", "channelEvent"] as const;
-const VALID_SPAWN_PROVIDERS = ["claude", "codex"] as const;
-const VALID_SPAWN_APPROVALS = ["open", "guarded", "read-only"] as const;
-const VALID_PROVIDER_EFFORTS = ["low", "medium", "high", "xhigh", "max"] as const;
+
 
 const TOOLS: ToolDefinition[] = [
   {
@@ -201,13 +200,13 @@ const TOOLS: ToolDefinition[] = [
     inputSchema: {
       type: "object",
       properties: {
-        provider: { type: "string", enum: VALID_SPAWN_PROVIDERS },
+        provider: { type: "string", enum: SPAWN_PROVIDERS },
         orchestratorId: { type: "string" },
         cwd: { type: "string" },
         label: { type: "string" },
         model: { type: "string" },
-        effort: { type: "string", enum: VALID_PROVIDER_EFFORTS },
-        approvalMode: { type: "string", enum: VALID_SPAWN_APPROVALS },
+        effort: { type: "string", enum: VALID_EFFORTS },
+        approvalMode: { type: "string", enum: APPROVAL_MODES },
         prompt: { type: "string" },
         systemPromptAppend: { type: "string" },
         tags: { type: "array", items: { type: "string" } },
@@ -519,16 +518,16 @@ function relayAgentStatus(args: Record<string, unknown>): Record<string, unknown
 }
 
 function relaySpawnAgent(auth: McpAuthContext, args: Record<string, unknown>): Record<string, unknown> {
-  const provider = enumField(args.provider, "provider", VALID_SPAWN_PROVIDERS) as SpawnProvider;
+  const provider = enumField(args.provider, "provider", SPAWN_PROVIDERS) as SpawnProvider;
   const cwd = optionalString(args.cwd, "cwd", 500);
   const orchestrator = selectSpawnOrchestrator(provider, optionalString(args.orchestratorId, "orchestratorId", 200), cwd);
   const resolvedCwd = cwd || orchestrator.baseDir;
-  if (cwd && !pathWithinBase(cwd, orchestrator.baseDir)) {
+  if (cwd && !isPathWithinBase(cwd, orchestrator.baseDir)) {
     throw new ValidationError(`cwd must be within orchestrator base directory: ${orchestrator.baseDir}`);
   }
   const selection = providerSelection(provider, args);
-  const approvalMode = optionalEnum(args.approvalMode, "approvalMode", VALID_SPAWN_APPROVALS) as SpawnApprovalMode | undefined ?? "guarded";
-  const spawnRequestId = optionalString(args.spawnRequestId, "spawnRequestId", 160) ?? `sp_${randomUUID()}`;
+  const approvalMode = optionalEnum(args.approvalMode, "approvalMode", APPROVAL_MODES) as SpawnApprovalMode | undefined ?? "guarded";
+  const spawnRequestId = optionalString(args.spawnRequestId, "spawnRequestId", 160) ?? generateSpawnRequestId();
   const label = optionalString(args.label, "label", 120);
   const policyName = optionalString(args.policyName, "policyName", 120);
   assertComponentResourceAllowed(auth, {
@@ -558,12 +557,9 @@ function relaySpawnAgent(auth: McpAuthContext, args: Record<string, unknown>): R
     source: "system",
     target: orchestrator.agentId,
     correlationId: spawnRequestId,
-    params: {
-      action: "spawn",
+    params: buildSpawnCommand({
       provider,
-      model: selection.model,
-      providerModel: selection.providerModel,
-      effort: selection.effort,
+      modelParams: selection,
       cwd: resolvedCwd,
       label,
       tags: optionalStringArray(args.tags, "tags") ?? [],
@@ -580,7 +576,7 @@ function relaySpawnAgent(auth: McpAuthContext, args: Record<string, unknown>): R
       requestedVia: "mcp",
       requestedAt: Date.now(),
       orchestratorId: orchestrator.id,
-    },
+    }),
   });
   emitCommand(command);
   return { ok: true, orchestratorId: orchestrator.id, provider, command };
@@ -714,7 +710,7 @@ function selectSpawnOrchestrator(provider: SpawnProvider, orchestratorId?: strin
   }
   const candidates = listOrchestrators().filter((item) => item.status === "online" && item.providers.includes(provider));
   if (cwd) {
-    const match = candidates.find((item) => pathWithinBase(cwd, item.baseDir));
+    const match = candidates.find((item) => isPathWithinBase(cwd, item.baseDir));
     if (match) return match;
   }
   const orchestrator = candidates[0];
@@ -771,26 +767,10 @@ function findManagedOrchestrator(input: {
   )) ?? null;
 }
 
-function providerSelection(provider: SpawnProvider, args: Record<string, unknown>): { model?: string; effort?: ProviderEffort; providerModel?: string } {
+function providerSelection(provider: SpawnProvider, args: Record<string, unknown>): SpawnModelParams {
   const model = optionalString(args.model, "model", 120);
-  const effort = optionalEnum(args.effort, "effort", VALID_PROVIDER_EFFORTS) as ProviderEffort | undefined;
-  try {
-    const resolved = resolveProviderSelection({ provider, model, effort });
-    return {
-      model: resolved.modelAlias,
-      providerModel: resolved.providerModel,
-      effort: resolved.effort,
-    };
-  } catch (error) {
-    throw new ValidationError(error instanceof Error ? error.message : String(error));
-  }
-}
-
-function pathWithinBase(path: string, baseDir: string): boolean {
-  const base = resolve(baseDir);
-  const target = resolve(path);
-  const rel = relative(base, target);
-  return rel === "" || (!!rel && !rel.startsWith("..") && !isAbsolute(rel));
+  const effort = optionalEnum(args.effort, "effort", VALID_EFFORTS) as ProviderEffort | undefined;
+  return resolveSpawnModelParams(provider, model, effort);
 }
 
 function bytesToStream(bytes: Uint8Array): ReadableStream<Uint8Array> {
@@ -937,10 +917,6 @@ function auditToolCall(
   }
 }
 
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-
 function recordField(value: unknown, field: string): Record<string, unknown> {
   if (!isRecord(value)) throw new ValidationError(`${field} must be an object`);
   return value;

package/src/memory-broker-smoke.ts

@@ -1,3 +1,5 @@
+import { RELAY_TOKEN_HEADER } from "agent-relay-sdk";
+
 interface MemoryBrokerSmokeOptions {
   baseUrl?: string;
   token?: string;
@@ -39,7 +41,7 @@ export async function runMemoryBrokerSmoke(options: MemoryBrokerSmokeOptions = {
 
   const request = async <T>(method: string, path: string, body?: unknown): Promise<T> => {
     const headers: Record<string, string> = {};
-    if (token) headers["X-Agent-Relay-Token"] = token;
+    if (token) headers[RELAY_TOKEN_HEADER] = token;
     if (body !== undefined) headers["Content-Type"] = "application/json";
     const response = await fetchImpl(new URL(path, baseUrl), {
       method,

package/src/memory-command-broker.ts

@@ -20,6 +20,7 @@ import {
   normalizeMemorySearchResult,
 } from "./memory-broker-contract";
 import { normalizeContextPackage } from "./memory-http-broker";
+import { isRecord } from "agent-relay-sdk";
 
 const DEFAULT_TIMEOUT_MS = 10_000;
 
@@ -155,7 +156,3 @@ 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 isRecord(value: unknown): value is Record<string, unknown> {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
-}

package/src/memory-http-broker.ts

@@ -19,6 +19,7 @@ import {
   normalizeMemoryBrokerCapabilities,
   normalizeMemorySearchResult,
 } from "./memory-broker-contract";
+import { isRecord } from "agent-relay-sdk";
 
 const DEFAULT_TIMEOUT_MS = 10_000;
 
@@ -182,7 +183,3 @@ function requireRecord(value: unknown, field: string): Record<string, unknown> {
   if (!isRecord(value)) throw new MemoryBrokerContractError(`${field} must be an object`);
   return value;
 }
-
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
-}

package/src/memory-service.ts

@@ -1,5 +1,6 @@
 import { createCommand } from "./commands-db";
 import { getAgent, ValidationError } from "./db";
+import { isRecord } from "agent-relay-sdk";
 import { assembleContextPackage, contextBudgetForAgent, estimateMemoryTokens } from "./memory-broker";
 import { createMemoryBrokerRegistry, memoryBrokerConfigFromEnv } from "./memory-broker-registry";
 import { filterMemoriesForInjection, formatUntrustedMemoryBlock } from "./memory-broker-contract";
@@ -349,7 +350,3 @@ function stringArray(value: unknown): string[] | undefined {
 function isPositiveInteger(value: unknown): value is number {
   return typeof value === "number" && Number.isSafeInteger(value) && value > 0;
 }
-
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
-}

package/src/memory-sqlite-broker.ts

@@ -1,6 +1,7 @@
 import { randomUUID } from "node:crypto";
 import type { Database } from "bun:sqlite";
 import { getDb, ValidationError } from "./db";
+import { parseJson } from "./utils";
 import type {
   ActiveMemoryClearReason,
   ContextPackage,
@@ -327,14 +328,6 @@ function rowToMemory(row: MemoryRow): Memory {
   });
 }
 
-function parseJson<T>(raw: string, fallback: T): T {
-  try {
-    return JSON.parse(raw) as T;
-  } catch {
-    return fallback;
-  }
-}
-
 function tagOverlap(tags: string[], queryTags: Set<string>): number {
   if (queryTags.size === 0) return 0;
   const memoryTags = new Set(tags.map((tag) => tag.toLowerCase()));

package/src/provider-catalog-store.ts

@@ -3,10 +3,10 @@ import {
   type ProviderCatalogEntry,
   type ProviderModelCatalogEntry,
 } from "agent-relay-sdk/provider-catalog";
+import { SPAWN_PROVIDERS } from "agent-relay-sdk";
 import type { SpawnProvider } from "./types";
 import { getDb, ValidationError } from "./db";
-
-const VALID_PROVIDERS: SpawnProvider[] = ["claude", "codex"];
+import { parseJson } from "./utils";
 
 interface ProviderModelOverrideRow {
   provider: SpawnProvider;
@@ -111,7 +111,7 @@ export function mergeProviderCatalog(
 }
 
 function normalizeOverrideInput(input: ProviderModelOverrideInput): ProviderModelOverrideInput {
-  if (!VALID_PROVIDERS.includes(input.provider)) throw new ValidationError("provider must be claude or codex");
+  if (!SPAWN_PROVIDERS.includes(input.provider)) throw new ValidationError("provider must be claude or codex");
   const alias = input.alias.trim();
   if (!alias) throw new ValidationError("model alias is required");
   if (input.entry.alias !== alias) throw new ValidationError("model entry alias must match override alias");
@@ -154,11 +154,3 @@ function cloneProviderEntry(entry: ProviderCatalogEntry): ProviderCatalogEntry {
 function cloneModelEntry(entry: ProviderModelCatalogEntry): ProviderModelCatalogEntry {
   return JSON.parse(JSON.stringify(entry)) as ProviderModelCatalogEntry;
 }
-
-function parseJson<T>(raw: string, fallback: T): T {
-  try {
-    return JSON.parse(raw) as T;
-  } catch {
-    return fallback;
-  }
-}

package/src/recipe-loader.ts

@@ -2,6 +2,7 @@ import { existsSync, readFileSync, readdirSync } from "node:fs";
 import { basename, join, resolve } from "node:path";
 import { validateRecipe } from "./recipe-validator";
 import type { Recipe } from "./types";
+import { isRecord } from "agent-relay-sdk";
 
 interface LoadedRecipe {
   name: string;
@@ -113,7 +114,3 @@ function parseScalar(value: string): unknown {
   if (/^\d+$/.test(trimmed)) return Number(trimmed);
   return trimmed.replace(/^["']|["']$/g, "");
 }
-
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
-}

package/src/recipe-validator.ts

@@ -1,5 +1,6 @@
 import type { MemoryType, Recipe, RecipeAgent, RecipeMemoryPolicy } from "./types";
 import { resolveProviderSelection, type ProviderEffort } from "agent-relay-sdk/provider-catalog";
+import { isRecord } from "agent-relay-sdk";
 
 class RecipeValidationError extends Error {}
 
@@ -131,7 +132,3 @@ function optionalPositiveInteger(value: unknown, field: string): number | undefi
   if (typeof value !== "number" || !Number.isSafeInteger(value) || value <= 0) throw new RecipeValidationError(`${field} must be a positive integer`);
   return value;
 }
-
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
-}