@rk0429/agentic-relay 1.2.0 → 1.3.1

package/dist/relay.mjs

@@ -46,6 +46,120 @@ var init_logger = __esm({
   }
 });
 
+// src/core/metadata-validation.ts
+function isPlainObject(value) {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    return false;
+  }
+  const prototype = Object.getPrototypeOf(value);
+  return prototype === Object.prototype || prototype === null;
+}
+function utf8Size(value) {
+  return new TextEncoder().encode(value).length;
+}
+function validateMetadataKey(key) {
+  if (DANGEROUS_METADATA_KEYS.has(key)) {
+    throw new Error(`metadata key "${key}" is not allowed`);
+  }
+  if (key.length > MAX_METADATA_KEY_LENGTH) {
+    throw new Error(
+      `metadata key "${key}" exceeds ${MAX_METADATA_KEY_LENGTH} chars`
+    );
+  }
+}
+function validateMetadataValue(value, path2, depth) {
+  if (depth > MAX_METADATA_NESTING_DEPTH) {
+    throw new Error(
+      `metadata nesting depth exceeds ${MAX_METADATA_NESTING_DEPTH} at "${path2}"`
+    );
+  }
+  if (typeof value === "string") {
+    if (value.length > MAX_METADATA_STRING_VALUE_LENGTH) {
+      throw new Error(
+        `metadata string at "${path2}" exceeds ${MAX_METADATA_STRING_VALUE_LENGTH} chars`
+      );
+    }
+    return;
+  }
+  if (value === null || value === void 0 || typeof value === "number" || typeof value === "boolean") {
+    return;
+  }
+  if (Array.isArray(value)) {
+    for (let index = 0; index < value.length; index += 1) {
+      validateMetadataValue(value[index], `${path2}[${index}]`, depth + 1);
+    }
+    return;
+  }
+  if (typeof value === "object") {
+    if (!isPlainObject(value)) {
+      throw new Error(`metadata value at "${path2}" must be a plain object`);
+    }
+    for (const [key, nestedValue] of Object.entries(value)) {
+      validateMetadataKey(key);
+      validateMetadataValue(nestedValue, `${path2}.${key}`, depth + 1);
+    }
+    return;
+  }
+  throw new Error(`metadata value at "${path2}" has unsupported type`);
+}
+function validateMetadata(raw) {
+  if (raw === void 0 || raw === null) {
+    return {};
+  }
+  if (!isPlainObject(raw)) {
+    throw new Error("metadata must be a plain object");
+  }
+  let serialized;
+  try {
+    serialized = JSON.stringify(raw);
+  } catch {
+    throw new Error("metadata must be JSON-serializable");
+  }
+  if (utf8Size(serialized) > MAX_METADATA_SIZE_BYTES) {
+    throw new Error(`metadata exceeds ${MAX_METADATA_SIZE_BYTES} bytes`);
+  }
+  const entries = Object.entries(raw);
+  if (entries.length > MAX_METADATA_KEY_COUNT) {
+    throw new Error(`metadata has ${entries.length} keys, max is ${MAX_METADATA_KEY_COUNT}`);
+  }
+  for (const [key, value] of entries) {
+    validateMetadataKey(key);
+    validateMetadataValue(value, key, 1);
+  }
+  const typed = raw;
+  if (typed.taskId !== void 0 && typeof typed.taskId !== "string") {
+    throw new Error("metadata.taskId must be a string");
+  }
+  if (typed.taskId !== void 0 && typeof typed.taskId === "string" && !TASK_ID_PATTERN.test(typed.taskId)) {
+    throw new Error("metadata.taskId must match ^(TASK|GOAL)-\\d{3,}$");
+  }
+  if (typed.agentType !== void 0 && typeof typed.agentType !== "string") {
+    throw new Error("metadata.agentType must be a string");
+  }
+  if (typed.label !== void 0 && typeof typed.label !== "string") {
+    throw new Error("metadata.label must be a string");
+  }
+  if (typed.tags !== void 0) {
+    if (!Array.isArray(typed.tags) || !typed.tags.every((tag) => typeof tag === "string")) {
+      throw new Error("metadata.tags must be string[]");
+    }
+  }
+  return typed;
+}
+var DANGEROUS_METADATA_KEYS, TASK_ID_PATTERN, MAX_METADATA_SIZE_BYTES, MAX_METADATA_KEY_COUNT, MAX_METADATA_KEY_LENGTH, MAX_METADATA_STRING_VALUE_LENGTH, MAX_METADATA_NESTING_DEPTH;
+var init_metadata_validation = __esm({
+  "src/core/metadata-validation.ts"() {
+    "use strict";
+    DANGEROUS_METADATA_KEYS = /* @__PURE__ */ new Set(["__proto__", "constructor", "prototype"]);
+    TASK_ID_PATTERN = /^(TASK|GOAL)-\d{3,}$/;
+    MAX_METADATA_SIZE_BYTES = 8 * 1024;
+    MAX_METADATA_KEY_COUNT = 20;
+    MAX_METADATA_KEY_LENGTH = 64;
+    MAX_METADATA_STRING_VALUE_LENGTH = 1024;
+    MAX_METADATA_NESTING_DEPTH = 3;
+  }
+});
+
 // src/mcp-server/deferred-cleanup-task-store.ts
 import { isTerminal } from "@modelcontextprotocol/sdk/experimental/tasks/interfaces.js";
 import { randomBytes } from "crypto";
@@ -856,116 +970,16 @@ function buildChildMcpServers(parentMcpServers, childHttpUrl) {
   }
   return result;
 }
-function isPlainObject2(value) {
-  if (typeof value !== "object" || value === null || Array.isArray(value)) {
-    return false;
-  }
-  const prototype = Object.getPrototypeOf(value);
-  return prototype === Object.prototype || prototype === null;
-}
-function utf8Size(value) {
-  return new TextEncoder().encode(value).length;
-}
-function validateMetadataKey(key) {
-  if (DANGEROUS_METADATA_KEYS.has(key)) {
-    throw new Error(`metadata key "${key}" is not allowed`);
-  }
-  if (key.length > MAX_METADATA_KEY_LENGTH) {
-    throw new Error(
-      `metadata key "${key}" exceeds ${MAX_METADATA_KEY_LENGTH} chars`
-    );
-  }
-}
-function validateMetadataValue(value, path2, depth) {
-  if (depth > MAX_METADATA_NESTING_DEPTH) {
-    throw new Error(
-      `metadata nesting depth exceeds ${MAX_METADATA_NESTING_DEPTH} at "${path2}"`
-    );
-  }
-  if (typeof value === "string") {
-    if (value.length > MAX_METADATA_STRING_VALUE_LENGTH) {
-      throw new Error(
-        `metadata string at "${path2}" exceeds ${MAX_METADATA_STRING_VALUE_LENGTH} chars`
-      );
-    }
-    return;
-  }
-  if (value === null || value === void 0 || typeof value === "number" || typeof value === "boolean") {
-    return;
-  }
-  if (Array.isArray(value)) {
-    for (let index = 0; index < value.length; index += 1) {
-      validateMetadataValue(value[index], `${path2}[${index}]`, depth + 1);
-    }
-    return;
-  }
-  if (typeof value === "object") {
-    if (!isPlainObject2(value)) {
-      throw new Error(`metadata value at "${path2}" must be a plain object`);
-    }
-    for (const [key, nestedValue] of Object.entries(value)) {
-      validateMetadataKey(key);
-      validateMetadataValue(nestedValue, `${path2}.${key}`, depth + 1);
-    }
-    return;
-  }
-  throw new Error(`metadata value at "${path2}" has unsupported type`);
-}
-function validateMetadata(raw) {
-  if (raw === void 0 || raw === null) {
-    return {};
-  }
-  if (!isPlainObject2(raw)) {
-    throw new Error("metadata must be a plain object");
-  }
-  let serialized;
-  try {
-    serialized = JSON.stringify(raw);
-  } catch {
-    throw new Error("metadata must be JSON-serializable");
+function resolveValidatedSessionMetadata(input) {
+  const validated = validateMetadata(input.metadata);
+  const mergedMetadata = { ...validated };
+  if (mergedMetadata.agentType === void 0 && input.agent !== void 0) {
+    mergedMetadata.agentType = input.agent;
   }
-  if (utf8Size(serialized) > MAX_METADATA_SIZE_BYTES) {
-    throw new Error(`metadata exceeds ${MAX_METADATA_SIZE_BYTES} bytes`);
-  }
-  const entries = Object.entries(raw);
-  if (entries.length > MAX_METADATA_KEY_COUNT) {
-    throw new Error(`metadata has ${entries.length} keys, max is ${MAX_METADATA_KEY_COUNT}`);
-  }
-  for (const [key, value] of entries) {
-    validateMetadataKey(key);
-    validateMetadataValue(value, key, 1);
-  }
-  const typed = raw;
-  if (typed.taskId !== void 0 && typeof typed.taskId !== "string") {
-    throw new Error("metadata.taskId must be a string");
+  if (mergedMetadata.label === void 0 && input.label !== void 0) {
+    mergedMetadata.label = input.label;
   }
-  if (typed.taskId !== void 0 && typeof typed.taskId === "string" && !TASK_ID_PATTERN.test(typed.taskId)) {
-    throw new Error("metadata.taskId must match ^(TASK|GOAL)-\\d{3,}$");
-  }
-  if (typed.agentType !== void 0 && typeof typed.agentType !== "string") {
-    throw new Error("metadata.agentType must be a string");
-  }
-  if (typed.label !== void 0 && typeof typed.label !== "string") {
-    throw new Error("metadata.label must be a string");
-  }
-  if (typed.tags !== void 0) {
-    if (!Array.isArray(typed.tags) || !typed.tags.every((tag) => typeof tag === "string")) {
-      throw new Error("metadata.tags must be string[]");
-    }
-  }
-  return typed;
-}
-function getLastActivityAtMs(session) {
-  return Math.max(
-    session.lastHeartbeatAt.getTime(),
-    session.updatedAt.getTime()
-  );
-}
-function isActiveSessionStale(session, staleThresholdMs, now) {
-  if (session.status !== "active") {
-    return false;
-  }
-  return getLastActivityAtMs(session) + staleThresholdMs < now;
+  return validateMetadata(mergedMetadata);
 }
 function inferFailureReason(stderr, stdout, sdkErrorMetadata) {
   if (sdkErrorMetadata) {
@@ -984,10 +998,6 @@ function failureReasonToErrorCode(reason) {
       return "RELAY_RECURSION_BLOCKED";
     case "metadata_validation":
       return "RELAY_METADATA_VALIDATION";
-    case "max_sessions_exceeded":
-      return "RELAY_MAX_SESSIONS_EXCEEDED";
-    case "concurrent_limit_race":
-      return "RELAY_CONCURRENT_LIMIT_RACE";
     case "backend_unavailable":
       return "RELAY_BACKEND_UNAVAILABLE";
     case "instruction_file_error":
@@ -1017,7 +1027,7 @@ function buildContextFromEnv() {
   const depth = Number(process.env["RELAY_DEPTH"] ?? "0");
   return { traceId, parentSessionId, depth };
 }
-async function executeSpawnAgent(input, registry2, sessionManager2, guard, hooksEngine2, contextMonitor2, backendSelector, childHttpUrl, onProgress, agentEventStore, hookMemoryDir = "./memory", sessionHealthConfig) {
+async function executeSpawnAgent(input, registry2, sessionManager2, guard, hooksEngine2, contextMonitor2, backendSelector, childHttpUrl, onProgress, agentEventStore, hookMemoryDir = "./memory") {
   onProgress?.({ stage: "initializing", percent: 0 });
   let effectiveBackend;
   let selectionReason;
@@ -1073,15 +1083,7 @@ async function executeSpawnAgent(input, registry2, sessionManager2, guard, hooks
   const spawnStartedAt = (/* @__PURE__ */ new Date()).toISOString();
   let validatedMetadata;
   try {
-    validatedMetadata = validateMetadata(input.metadata);
-    const mergedMetadata = { ...validatedMetadata };
-    if (mergedMetadata.agentType === void 0 && input.agent !== void 0) {
-      mergedMetadata.agentType = input.agent;
-    }
-    if (mergedMetadata.label === void 0 && input.label !== void 0) {
-      mergedMetadata.label = input.label;
-    }
-    validatedMetadata = validateMetadata(mergedMetadata);
+    validatedMetadata = resolveValidatedSessionMetadata(input);
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error);
     return {
@@ -1092,79 +1094,22 @@ async function executeSpawnAgent(input, registry2, sessionManager2, guard, hooks
       failureReason: "metadata_validation"
     };
   }
-  const maxActiveSessions = Math.max(
-    1,
-    sessionHealthConfig?.maxActiveSessions ?? DEFAULT_MAX_ACTIVE_SESSIONS
-  );
-  const staleThresholdMs = Math.max(
-    1,
-    sessionHealthConfig?.staleThresholdMs ?? DEFAULT_STALE_THRESHOLD_MS
-  );
-  const warnThreshold = Math.ceil(maxActiveSessions * 0.8);
-  const maxCreateAttempts = 3;
-  let session = null;
-  let lastCreateError = "";
-  for (let attempt = 0; attempt < maxCreateAttempts; attempt += 1) {
-    const activeSessions = await sessionManager2.list({ status: "active" });
-    const now = Date.now();
-    const activeHealthyCount = activeSessions.filter(
-      (activeSession) => !isActiveSessionStale(activeSession, staleThresholdMs, now)
-    ).length;
-    if (activeHealthyCount >= maxActiveSessions) {
-      return {
-        sessionId: "",
-        exitCode: 1,
-        stdout: "",
-        stderr: `RELAY_MAX_SESSIONS_EXCEEDED: active sessions ${activeHealthyCount}/${maxActiveSessions}`,
-        failureReason: "max_sessions_exceeded"
-      };
-    }
-    if (activeHealthyCount >= warnThreshold) {
-      logger.warn(
-        `Active session usage high during spawn: ${activeHealthyCount}/${maxActiveSessions}`
-      );
-    }
-    try {
-      session = await sessionManager2.create({
-        backendId: effectiveBackend,
-        parentSessionId: envContext.parentSessionId ?? void 0,
-        depth: envContext.depth + 1,
-        metadata: validatedMetadata,
-        expectedActiveCount: activeHealthyCount,
-        expectedActiveStaleThresholdMs: staleThresholdMs
-      });
-      break;
-    } catch (error) {
-      const message = error instanceof Error ? error.message : String(error);
-      lastCreateError = message;
-      if (message.includes("RELAY_CONCURRENT_LIMIT_RACE") && attempt < maxCreateAttempts - 1) {
-        continue;
-      }
-      if (message.includes("RELAY_CONCURRENT_LIMIT_RACE")) {
-        return {
-          sessionId: "",
-          exitCode: 1,
-          stdout: "",
-          stderr: message,
-          failureReason: "concurrent_limit_race"
-        };
-      }
-      return {
-        sessionId: "",
-        exitCode: 1,
-        stdout: "",
-        stderr: message,
-        failureReason: "unknown"
-      };
-    }
-  }
-  if (!session) {
+  let session;
+  try {
+    session = await sessionManager2.create({
+      backendId: effectiveBackend,
+      parentSessionId: envContext.parentSessionId ?? void 0,
+      depth: envContext.depth + 1,
+      metadata: validatedMetadata
+    });
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
     return {
       sessionId: "",
       exitCode: 1,
       stdout: "",
-      stderr: lastCreateError || "RELAY_CONCURRENT_LIMIT_RACE: failed to create session",
-      failureReason: "concurrent_limit_race"
+      stderr: message,
+      failureReason: "unknown"
     };
   }
   agentEventStore?.record({
@@ -1626,21 +1571,13 @@ ${input.prompt}`;
     };
   }
 }
-var DANGEROUS_METADATA_KEYS, TASK_ID_PATTERN, MAX_METADATA_SIZE_BYTES, MAX_METADATA_KEY_COUNT, MAX_METADATA_KEY_LENGTH, MAX_METADATA_STRING_VALUE_LENGTH, MAX_METADATA_NESTING_DEPTH, DEFAULT_MAX_ACTIVE_SESSIONS, DEFAULT_STALE_THRESHOLD_MS, spawnAgentInputSchema;
+var spawnAgentInputSchema;
 var init_spawn_agent = __esm({
   "src/mcp-server/tools/spawn-agent.ts"() {
     "use strict";
     init_recursion_guard();
     init_logger();
-    DANGEROUS_METADATA_KEYS = /* @__PURE__ */ new Set(["__proto__", "constructor", "prototype"]);
-    TASK_ID_PATTERN = /^(TASK|GOAL)-\d{3,}$/;
-    MAX_METADATA_SIZE_BYTES = 8 * 1024;
-    MAX_METADATA_KEY_COUNT = 20;
-    MAX_METADATA_KEY_LENGTH = 64;
-    MAX_METADATA_STRING_VALUE_LENGTH = 1024;
-    MAX_METADATA_NESTING_DEPTH = 3;
-    DEFAULT_MAX_ACTIVE_SESSIONS = 20;
-    DEFAULT_STALE_THRESHOLD_MS = 3e5;
+    init_metadata_validation();
     spawnAgentInputSchema = z2.object({
       fallbackBackend: z2.enum(["claude", "codex", "gemini"]).optional().describe(
         "Optional fallback backend. Used only when BackendSelector is not active or cannot determine a backend. When BackendSelector is active, backend is auto-selected by priority: preferredBackend > agentType mapping > taskType mapping > default (claude)."
@@ -1780,7 +1717,31 @@ var init_conflict_detector = __esm({
 });
 
 // src/mcp-server/tools/spawn-agents-parallel.ts
-async function executeSpawnAgentsParallel(agents, registry2, sessionManager2, guard, hooksEngine2, contextMonitor2, backendSelector, childHttpUrl, onProgress, agentEventStore, hookMemoryDir = "./memory", sessionHealthConfig) {
+async function executeSpawnAgentsParallel(agents, registry2, sessionManager2, guard, hooksEngine2, contextMonitor2, backendSelector, childHttpUrl, onProgress, agentEventStore, hookMemoryDir = "./memory") {
+  for (let index = 0; index < agents.length; index += 1) {
+    try {
+      resolveValidatedSessionMetadata(agents[index]);
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      const reason = `RELAY_METADATA_VALIDATION: agent index ${index}: ${message}`;
+      return {
+        results: agents.map((agent, resultIndex) => ({
+          index: resultIndex,
+          sessionId: "",
+          exitCode: 1,
+          stdout: "",
+          stderr: reason,
+          error: reason,
+          failureReason: "metadata_validation",
+          ...agent.label ? { label: agent.label } : {},
+          originalInput: agent
+        })),
+        totalCount: agents.length,
+        successCount: 0,
+        failureCount: agents.length
+      };
+    }
+  }
   const envContext = buildContextFromEnv();
   if (envContext.depth >= guard.getConfig().maxDepth) {
     const reason = `Max depth exceeded: ${envContext.depth} >= ${guard.getConfig().maxDepth}`;
@@ -1839,8 +1800,7 @@ async function executeSpawnAgentsParallel(agents, registry2, sessionManager2, gu
         childHttpUrl,
         void 0,
         agentEventStore,
-        hookMemoryDir,
-        sessionHealthConfig
+        hookMemoryDir
       ).then((result) => {
         completedCount++;
         onProgress?.({
@@ -1911,21 +1871,22 @@ var init_spawn_agents_parallel = __esm({
 // src/mcp-server/tools/list-sessions.ts
 import { z as z3 } from "zod";
 async function executeListSessions(input, sessionManager2, options) {
-  const normalizedBackendId = input.backendId ?? input.backend;
-  if (input.backendId && input.backend && input.backendId !== input.backend) {
+  const validatedInput = listSessionsInputSchema.parse(input);
+  const normalizedBackendId = validatedInput.backendId ?? validatedInput.backend;
+  if (validatedInput.backendId && validatedInput.backend && validatedInput.backendId !== validatedInput.backend) {
     logger.warn(
-      `list_sessions: both backendId and backend were provided; backendId="${input.backendId}" is used`
+      `list_sessions: both backendId and backend were provided; backendId="${validatedInput.backendId}" is used`
     );
   }
   const staleThresholdMs = (options?.staleThresholdSec ?? 300) * 1e3;
   const sessions = await sessionManager2.list({
     backendId: normalizedBackendId,
-    limit: input.limit,
-    status: input.staleOnly ? "active" : input.status,
-    taskId: input.taskId,
-    label: input.label,
-    tags: input.tags,
-    staleOnly: input.staleOnly ?? false,
+    limit: validatedInput.limit,
+    status: validatedInput.staleOnly ? "active" : validatedInput.status,
+    taskId: validatedInput.taskId,
+    label: validatedInput.label,
+    tags: validatedInput.tags,
+    staleOnly: validatedInput.staleOnly ?? false,
     staleThresholdMs
   });
   return {
@@ -1946,12 +1907,13 @@ var init_list_sessions = __esm({
   "src/mcp-server/tools/list-sessions.ts"() {
     "use strict";
     init_logger();
+    init_metadata_validation();
     listSessionsInputSchema = z3.object({
       backendId: z3.enum(["claude", "codex", "gemini"]).optional(),
       backend: z3.enum(["claude", "codex", "gemini"]).optional(),
       limit: z3.number().int().min(1).max(100).optional().default(10),
       status: z3.enum(["active", "completed", "error"]).optional(),
-      taskId: z3.string().optional(),
+      taskId: z3.string().regex(TASK_ID_PATTERN).optional(),
       label: z3.string().optional(),
       tags: z3.array(z3.string()).optional(),
       staleOnly: z3.boolean().optional().default(false)
@@ -2351,6 +2313,7 @@ var init_server = __esm({
     init_get_context_status();
     init_list_available_backends();
     init_backend_selector();
+    init_metadata_validation();
     init_logger();
     init_types();
     init_response_formatter();
@@ -2372,7 +2335,6 @@ var init_server = __esm({
         this.guard = new RecursionGuard(guardConfig);
         this.backendSelector = new BackendSelector();
         this.staleThresholdSec = relayConfig?.sessionHealth?.staleThresholdSec ?? 300;
-        this.maxActiveSessions = relayConfig?.sessionHealth?.maxActiveSessions ?? 20;
         this.hookMemoryDir = relayConfig?.hooks?.memoryDir ?? "./memory";
         this.agentEventStore = new AgentEventStore({
           backend: relayConfig?.eventStore?.backend,
@@ -2400,7 +2362,7 @@ var init_server = __esm({
           this.agentEventStore
         );
         this.server = new McpServer(
-          { name: "agentic-relay", version: "1.2.0" },
+          { name: "agentic-relay", version: "1.3.1" },
           createMcpServerOptions()
         );
         this.registerTools(this.server);
@@ -2412,7 +2374,6 @@ var init_server = __esm({
       agentEventStore;
       sessionHealthMonitor;
       staleThresholdSec;
-      maxActiveSessions;
       hookMemoryDir;
       _childHttpServer;
       _childHttpUrl;
@@ -2442,11 +2403,7 @@ var init_server = __esm({
               this._childHttpUrl,
               void 0,
               this.agentEventStore,
-              this.hookMemoryDir,
-              {
-                maxActiveSessions: this.maxActiveSessions,
-                staleThresholdMs: this.staleThresholdSec * 1e3
-              }
+              this.hookMemoryDir
             );
             const controlOptions = {
               inlineSummaryLength: this.inlineSummaryLength ?? DEFAULT_INLINE_SUMMARY_LENGTH,
@@ -2501,11 +2458,7 @@ var init_server = __esm({
               this._childHttpUrl,
               void 0,
               this.agentEventStore,
-              this.hookMemoryDir,
-              {
-                maxActiveSessions: this.maxActiveSessions,
-                staleThresholdMs: this.staleThresholdSec * 1e3
-              }
+              this.hookMemoryDir
             );
             const controlOptions = {
               inlineSummaryLength: this.inlineSummaryLength ?? DEFAULT_INLINE_SUMMARY_LENGTH,
@@ -2626,11 +2579,7 @@ var init_server = __esm({
                 this._childHttpUrl,
                 void 0,
                 this.agentEventStore,
-                this.hookMemoryDir,
-                {
-                  maxActiveSessions: this.maxActiveSessions,
-                  staleThresholdMs: this.staleThresholdSec * 1e3
-                }
+                this.hookMemoryDir
               );
               const controlOptions = {
                 inlineSummaryLength: this.inlineSummaryLength ?? DEFAULT_INLINE_SUMMARY_LENGTH,
@@ -2658,7 +2607,7 @@ var init_server = __esm({
             backend: z7.enum(["claude", "codex", "gemini"]).optional().describe("Filter sessions by backend type."),
             limit: z7.number().int().min(1).max(100).optional().describe("Maximum number of sessions to return. Default: 10."),
             status: z7.enum(["active", "completed", "error"]).optional().describe("Filter sessions by status."),
-            taskId: z7.string().optional().describe("Filter by metadata.taskId."),
+            taskId: z7.string().regex(TASK_ID_PATTERN).optional().describe("Filter by metadata.taskId."),
             label: z7.string().optional().describe("Case-insensitive partial match for metadata.label."),
             tags: z7.array(z7.string()).optional().describe("Filter sessions containing all provided tags."),
             staleOnly: z7.boolean().optional().describe("When true, return only stale active sessions.")
@@ -2698,7 +2647,7 @@ var init_server = __esm({
         );
         server.tool(
           "check_session_health",
-          "Check relay session health without side effects.",
+          "Check whether a relay session is alive, stale, or completed. Use to verify sub-agent progress.",
           checkSessionHealthInputSchema.shape,
           async (params) => {
             try {
@@ -2728,7 +2677,7 @@ var init_server = __esm({
         );
         server.tool(
           "poll_agent_events",
-          "Poll agent lifecycle events using a cursor.",
+          "Get agent lifecycle events (spawned, completed, failed) since a cursor. Use for monitoring sub-agent progress.",
           pollAgentEventsInputSchema.shape,
           async (params) => {
             try {
@@ -2761,7 +2710,7 @@ var init_server = __esm({
         );
         server.tool(
           "get_context_status",
-          "Get the context usage status of a relay session. Returns usage data from ContextMonitor when available, otherwise estimated values.",
+          "Get context window usage of a relay session. Use to check if a sub-agent is approaching context limits.",
           {
             sessionId: z7.string().describe("Relay session ID to query context usage for.")
           },
@@ -2791,7 +2740,7 @@ var init_server = __esm({
         );
         server.tool(
           "list_available_backends",
-          "List all registered backends with their health status. Use this before spawn_agent to check which backends are available.",
+          "List registered backends and their health. spawn_agent auto-selects backends, so this is mainly for diagnostics.",
           {},
           async () => {
             try {
@@ -2881,7 +2830,7 @@ var init_server = __esm({
             sessionIdGenerator: () => randomUUID()
           });
           const server = new McpServer(
-            { name: "agentic-relay", version: "1.2.0" },
+            { name: "agentic-relay", version: "1.3.1" },
             createMcpServerOptions()
           );
           this.registerTools(server);
@@ -4291,7 +4240,8 @@ ${prompt}`;
 
 // src/core/session-manager.ts
 init_logger();
-import { readFile as readFile4, writeFile as writeFile4, readdir, mkdir as mkdir4, chmod, rename, unlink, open } from "fs/promises";
+init_metadata_validation();
+import { readFile as readFile4, writeFile as writeFile4, readdir, mkdir as mkdir4, chmod, rename, unlink } from "fs/promises";
 import { join as join4 } from "path";
 import { homedir as homedir4 } from "os";
 import { nanoid } from "nanoid";
@@ -4328,9 +4278,6 @@ function fromSessionData(data) {
 var SessionManager = class _SessionManager {
   static SESSION_ID_PATTERN = /^relay-[A-Za-z0-9_-]+$/;
   static DEFAULT_STALE_THRESHOLD_MS = 3e5;
-  static CREATE_LOCK_FILE = ".create.lock";
-  static CREATE_LOCK_RETRY_DELAY_MS = 10;
-  static CREATE_LOCK_MAX_RETRIES = 100;
   static PROTECTED_METADATA_KEYS = /* @__PURE__ */ new Set([
     "taskId",
     "parentTaskId",
@@ -4390,35 +4337,6 @@ var SessionManager = class _SessionManager {
     if (session.status !== "active") return false;
     return this.getLastActivityAtMs(session) + staleThresholdMs < now;
   }
-  async countHealthyActiveSessions(staleThresholdMs) {
-    const activeSessions = await this.list({ status: "active" });
-    const now = Date.now();
-    return activeSessions.filter(
-      (session) => !this.isStale(session, staleThresholdMs, now)
-    ).length;
-  }
-  async acquireCreateLock() {
-    await this.ensureDir();
-    const lockPath = join4(this.sessionsDir, _SessionManager.CREATE_LOCK_FILE);
-    for (let attempt = 0; attempt < _SessionManager.CREATE_LOCK_MAX_RETRIES; attempt += 1) {
-      try {
-        const handle = await open(lockPath, "wx", 384);
-        return async () => {
-          await handle.close().catch(() => void 0);
-          await unlink(lockPath).catch(() => void 0);
-        };
-      } catch (error) {
-        const code = error.code;
-        if (code !== "EEXIST") {
-          throw error;
-        }
-      }
-      await new Promise(
-        (resolve3) => setTimeout(resolve3, _SessionManager.CREATE_LOCK_RETRY_DELAY_MS)
-      );
-    }
-    throw new Error("RELAY_CONCURRENT_LIMIT_RACE: failed to acquire create lock");
-  }
   mergeMetadata(existing, updates) {
     const merged = { ...existing };
     for (const [key, value] of Object.entries(updates)) {
@@ -4432,36 +4350,23 @@ var SessionManager = class _SessionManager {
   }
   /** Create a new relay session. */
   async create(params) {
-    const releaseCreateLock = await this.acquireCreateLock();
-    try {
-      if (typeof params.expectedActiveCount === "number") {
-        const staleThresholdMs = params.expectedActiveStaleThresholdMs ?? _SessionManager.DEFAULT_STALE_THRESHOLD_MS;
-        const activeCount = await this.countHealthyActiveSessions(staleThresholdMs);
-        if (activeCount !== params.expectedActiveCount) {
-          throw new Error(
-            `RELAY_CONCURRENT_LIMIT_RACE: expected=${params.expectedActiveCount}, actual=${activeCount}`
-          );
-        }
-      }
-      const now = /* @__PURE__ */ new Date();
-      const session = {
-        relaySessionId: `relay-${nanoid()}`,
-        nativeSessionId: params.nativeSessionId ?? null,
-        backendId: params.backendId,
-        parentSessionId: params.parentSessionId ?? null,
-        depth: params.depth ?? 0,
-        createdAt: now,
-        updatedAt: now,
-        status: "active",
-        lastHeartbeatAt: now,
-        staleNotifiedAt: null,
-        metadata: params.metadata ?? {}
-      };
-      await this.writeSession(session);
-      return session;
-    } finally {
-      await releaseCreateLock();
-    }
+    await this.ensureDir();
+    const now = /* @__PURE__ */ new Date();
+    const session = {
+      relaySessionId: `relay-${nanoid()}`,
+      nativeSessionId: params.nativeSessionId ?? null,
+      backendId: params.backendId,
+      parentSessionId: params.parentSessionId ?? null,
+      depth: params.depth ?? 0,
+      createdAt: now,
+      updatedAt: now,
+      status: "active",
+      lastHeartbeatAt: now,
+      staleNotifiedAt: null,
+      metadata: validateMetadata(params.metadata)
+    };
+    await this.writeSession(session);
+    return session;
   }
   /** Update an existing session. */
   async update(relaySessionId, updates) {
@@ -4475,7 +4380,9 @@ var SessionManager = class _SessionManager {
     const updated = {
       ...session,
       ...updates,
-      metadata: updates.metadata ? this.mergeMetadata(session.metadata, updates.metadata) : session.metadata,
+      metadata: validateMetadata(
+        updates.metadata ? this.mergeMetadata(session.metadata, updates.metadata) : session.metadata
+      ),
       updatedAt: /* @__PURE__ */ new Date()
     };
     await this.writeSession(updated);
@@ -4720,7 +4627,7 @@ function deepMerge(target, source) {
   for (const key of Object.keys(source)) {
     const sourceVal = source[key];
     const targetVal = result[key];
-    if (isPlainObject(sourceVal) && isPlainObject(targetVal)) {
+    if (isPlainObject2(sourceVal) && isPlainObject2(targetVal)) {
       result[key] = deepMerge(
         targetVal,
         sourceVal
@@ -4731,14 +4638,14 @@ function deepMerge(target, source) {
   }
   return result;
 }
-function isPlainObject(value) {
+function isPlainObject2(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value) && Object.getPrototypeOf(value) === Object.prototype;
 }
 function getByPath(obj, path2) {
   const parts = path2.split(".");
   let current = obj;
   for (const part of parts) {
-    if (!isPlainObject(current)) return void 0;
+    if (!isPlainObject2(current)) return void 0;
     current = current[part];
   }
   return current;
@@ -4748,7 +4655,7 @@ function setByPath(obj, path2, value) {
   let current = obj;
   for (let i = 0; i < parts.length - 1; i++) {
     const part = parts[i];
-    if (!isPlainObject(current[part])) {
+    if (!isPlainObject2(current[part])) {
       current[part] = {};
     }
     current = current[part];
@@ -4857,7 +4764,7 @@ var ConfigManager = class {
     try {
       const raw = await readFile5(filePath, "utf-8");
       const parsed = JSON.parse(raw);
-      if (!isPlainObject(parsed)) return {};
+      if (!isPlainObject2(parsed)) return {};
       return parsed;
     } catch {
       return {};
@@ -6305,7 +6212,7 @@ function createVersionCommand(registry2) {
       description: "Show relay and backend versions"
     },
     async run() {
-      const relayVersion = "1.2.0";
+      const relayVersion = "1.3.1";
       console.log(`agentic-relay v${relayVersion}`);
       console.log("");
       console.log("Backends:");
@@ -6658,7 +6565,7 @@ void configManager.getConfig().then((config) => {
 var main = defineCommand10({
   meta: {
     name: "relay",
-    version: "1.2.0",
+    version: "1.3.1",
     description: "Unified CLI proxy for Claude Code, Codex CLI, and Gemini CLI"
   },
   subCommands: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rk0429/agentic-relay",
-  "version": "1.2.0",
+  "version": "1.3.1",
   "description": "Unified CLI proxy for Claude Code, Codex CLI, and Gemini CLI with MCP-based multi-layer sub-agent orchestration",
   "type": "module",
   "license": "Apache-2.0",