@rk0429/agentic-relay 0.8.0 → 0.9.1

package/dist/relay.mjs

@@ -18,6 +18,9 @@ function resolveLogLevel() {
   }
   return 3;
 }
+function redirectToStderr() {
+  logger.options.stdout = process.stderr;
+}
 var LOG_LEVEL_MAP, logger;
 var init_logger = __esm({
   "src/infrastructure/logger.ts"() {
@@ -307,6 +310,12 @@ function buildChildMcpServers(parentMcpServers, childHttpUrl) {
   }
   return result;
 }
+function inferFailureReason(stderr, stdout) {
+  const combined = `${stderr} ${stdout}`.toLowerCase();
+  if (combined.includes("timed out") || combined.includes("timeout")) return "timeout";
+  if (combined.includes("max turns") || combined.includes("max_turns") || combined.includes("turn limit")) return "max_turns_exhausted";
+  return "adapter_error";
+}
 function buildContextFromEnv() {
   const traceId = process.env["RELAY_TRACE_ID"] ?? `trace-${nanoid2()}`;
   const parentSessionId = process.env["RELAY_PARENT_SESSION_ID"] ?? null;
@@ -344,7 +353,8 @@ async function executeSpawnAgent(input, registry2, sessionManager2, guard, hooks
       sessionId: "",
       exitCode: 1,
       stdout: "",
-      stderr: `Spawn blocked: ${guardResult.reason}`
+      stderr: `Spawn blocked: ${guardResult.reason}`,
+      failureReason: "recursion_blocked"
     };
   }
   const adapter = registry2.get(effectiveBackend);
@@ -354,7 +364,8 @@ async function executeSpawnAgent(input, registry2, sessionManager2, guard, hooks
       sessionId: "",
       exitCode: 1,
       stdout: "",
-      stderr: `Backend "${effectiveBackend}" is not available. Use list_available_backends to see available options.`
+      stderr: `Backend "${effectiveBackend}" is not available. Use list_available_backends to see available options.`,
+      failureReason: "backend_unavailable"
     };
   }
   const spawnStartedAt = (/* @__PURE__ */ new Date()).toISOString();
@@ -446,7 +457,8 @@ ${wrapped}` : wrapped;
           sessionId: "",
           exitCode: 1,
           stdout: "",
-          stderr: `Task instruction file not found: ${input.taskInstructionPath}`
+          stderr: `Task instruction file not found: ${input.taskInstructionPath}`,
+          failureReason: "instruction_file_error"
         };
       }
       const instructionContent = readFileSync(safePath, "utf-8");
@@ -459,7 +471,8 @@ ${input.prompt}`;
         sessionId: "",
         exitCode: 1,
         stdout: "",
-        stderr: `Failed to read task instruction file: ${message}`
+        stderr: `Failed to read task instruction file: ${message}`,
+        failureReason: "instruction_file_error"
       };
     }
   }
@@ -473,7 +486,8 @@ ${input.prompt}`;
             exitCode: 1,
             stdout: "",
             stderr: `Backend "${effectiveBackend}" does not support session continuation (continueSession).`,
-            _noSession: true
+            _noSession: true,
+            _failureReason: "session_continuation_unsupported"
           };
         }
         return adapter.continueSession(input.resumeSessionId, effectivePrompt);
@@ -497,7 +511,8 @@ ${input.prompt}`;
             maxDepth: guard.getConfig().maxDepth,
             traceId: envContext.traceId
           },
-          ...mcpServers ? { mcpServers } : {}
+          ...mcpServers ? { mcpServers } : {},
+          ...input.timeoutMs ? { timeoutMs: input.timeoutMs } : {}
         });
       }
     })();
@@ -517,7 +532,8 @@ ${input.prompt}`;
         sessionId: session.relaySessionId,
         exitCode: result.exitCode,
         stdout: result.stdout,
-        stderr: result.stderr
+        stderr: result.stderr,
+        ..."_failureReason" in result ? { failureReason: result._failureReason } : {}
       };
     }
     onProgress?.({ stage: "executing", percent: 50 });
@@ -533,6 +549,7 @@ ${input.prompt}`;
     }
     guard.recordSpawn(context);
     const status = result.exitCode === 0 ? "completed" : "error";
+    const failureReason = result.exitCode !== 0 ? inferFailureReason(result.stderr, result.stdout) : void 0;
     await sessionManager2.update(session.relaySessionId, { status });
     const completedAt = (/* @__PURE__ */ new Date()).toISOString();
     const metadata = {
@@ -541,7 +558,8 @@ ${input.prompt}`;
       ...input.preferredBackend ? { requestedBackend: input.preferredBackend } : {},
       selectionReason,
       startedAt: spawnStartedAt,
-      completedAt
+      completedAt,
+      ...result.tokenUsage ? { tokenUsage: result.tokenUsage } : {}
     };
     onProgress?.({ stage: "completed", percent: 100 });
     if (hooksEngine2) {
@@ -581,16 +599,19 @@ ${input.prompt}`;
       stdout: result.stdout,
       stderr: result.stderr,
       nativeSessionId: result.nativeSessionId,
-      metadata
+      metadata,
+      ...failureReason ? { failureReason } : {}
     };
   } catch (error) {
     await sessionManager2.update(session.relaySessionId, { status: "error" });
     const message = error instanceof Error ? error.message : String(error);
+    const catchFailureReason = message.toLowerCase().includes("timed out") || message.toLowerCase().includes("timeout") ? "timeout" : "unknown";
     return {
       sessionId: session.relaySessionId,
       exitCode: 1,
       stdout: "",
-      stderr: message
+      stderr: message,
+      failureReason: catchFailureReason
     };
   }
 }
@@ -620,7 +641,8 @@ var init_spawn_agent = __esm({
       timeoutMs: z2.number().optional().describe("Timeout in milliseconds for agent execution. Default: no timeout."),
       taskInstructionPath: z2.string().optional().describe(
         "Path to a file containing task instructions. Content is prepended to the prompt. Path is resolved relative to the project root and validated against path traversal."
-      )
+      ),
+      label: z2.string().optional().describe("Human-readable label for identifying this agent in parallel results")
     });
   }
 });
@@ -723,13 +745,15 @@ async function executeSpawnAgentsParallel(agents, registry2, sessionManager2, gu
     const reason = `Max depth exceeded: ${envContext.depth} >= ${guard.getConfig().maxDepth}`;
     logger.warn(`Batch spawn blocked by RecursionGuard: ${reason}`);
     return {
-      results: agents.map((_, index) => ({
+      results: agents.map((agent, index) => ({
         index,
         sessionId: "",
         exitCode: 1,
         stdout: "",
         stderr: `Batch spawn blocked: ${reason}`,
-        error: reason
+        error: reason,
+        failureReason: "recursion_blocked",
+        ...agent.label ? { label: agent.label } : {}
       })),
       totalCount: agents.length,
       successCount: 0,
@@ -742,13 +766,15 @@ async function executeSpawnAgentsParallel(agents, registry2, sessionManager2, gu
     const reason = `Batch would exceed max calls per session: ${currentCount} + ${agents.length} > ${maxCalls}`;
     logger.warn(`Batch spawn blocked by RecursionGuard: ${reason}`);
     return {
-      results: agents.map((_, index) => ({
+      results: agents.map((agent, index) => ({
         index,
         sessionId: "",
         exitCode: 1,
         stdout: "",
         stderr: `Batch spawn blocked: ${reason}`,
-        error: reason
+        error: reason,
+        failureReason: "recursion_blocked",
+        ...agent.label ? { label: agent.label } : {}
       })),
       totalCount: agents.length,
       successCount: 0,
@@ -790,7 +816,9 @@ async function executeSpawnAgentsParallel(agents, registry2, sessionManager2, gu
         stdout: r.stdout,
         stderr: r.stderr,
         ...r.nativeSessionId ? { nativeSessionId: r.nativeSessionId } : {},
-        ...r.metadata ? { metadata: r.metadata } : {}
+        ...r.metadata ? { metadata: r.metadata } : {},
+        ...r.failureReason ? { failureReason: r.failureReason } : {},
+        ...agents[index]?.label ? { label: agents[index].label } : {}
       };
       if (r.exitCode !== 0) {
         base.originalInput = agents[index];
@@ -805,7 +833,9 @@ async function executeSpawnAgentsParallel(agents, registry2, sessionManager2, gu
       stdout: "",
       stderr: errorMessage,
       error: errorMessage,
-      originalInput: agents[index]
+      originalInput: agents[index],
+      failureReason: "unknown",
+      ...agents[index]?.label ? { label: agents[index].label } : {}
     };
   });
   const successCount = results.filter((r) => r.exitCode === 0).length;
@@ -979,6 +1009,70 @@ var init_backend_selector = __esm({
   }
 });
 
+// src/mcp-server/response-formatter.ts
+function formatSpawnAgentResponse(result) {
+  const isError = result.exitCode !== 0;
+  let text;
+  if (isError) {
+    const reasonPart = result.failureReason ? `, reason: ${result.failureReason}` : "";
+    text = `FAILED (exit ${result.exitCode}${reasonPart})`;
+    if (result.stderr) {
+      text += `
+${result.stderr}`;
+    }
+  } else {
+    text = `Session: ${result.sessionId}
+
+${result.stdout}`;
+  }
+  if (result.metadata) {
+    text += `
+
+<metadata>
+${JSON.stringify(result.metadata, null, 2)}
+</metadata>`;
+  }
+  return { text, isError };
+}
+function formatParallelResponse(result) {
+  const isError = result.failureCount === result.totalCount;
+  const parts = [];
+  if (result.hasConflicts && result.conflicts) {
+    parts.push(`\u26A0 FILE CONFLICTS DETECTED: Multiple agents modified the same files.`);
+    parts.push(`Conflicting files: ${result.conflicts.map((c) => c.path).join(", ")}
+`);
+  }
+  const durations = result.results.map((r) => r.metadata?.durationMs).filter((d) => d !== void 0);
+  const avgDuration = durations.length > 0 ? (durations.reduce((a, b) => a + b, 0) / durations.length / 1e3).toFixed(1) : "?";
+  parts.push(
+    `${result.totalCount} agents: ${result.successCount} succeeded, ${result.failureCount} failed (avg ${avgDuration}s)
+`
+  );
+  for (const r of result.results) {
+    const labelPart = r.label ? ` [${r.label}]` : "";
+    const backend = r.metadata?.selectedBackend ?? "?";
+    const duration = r.metadata?.durationMs !== void 0 ? `${(r.metadata.durationMs / 1e3).toFixed(1)}s` : "?s";
+    if (r.exitCode === 0) {
+      parts.push(`--- Agent ${r.index}${labelPart} (${backend}, ${duration}) SUCCESS ---`);
+      parts.push(r.stdout || "(no output)");
+    } else {
+      const reasonPart = r.failureReason ? `, reason: ${r.failureReason}` : "";
+      parts.push(`--- Agent ${r.index}${labelPart} FAILED (${backend}, ${duration}${reasonPart}) ---`);
+      parts.push(r.stderr || r.error || "(no output)");
+    }
+    parts.push("");
+  }
+  parts.push(`<metadata>
+${JSON.stringify(result, null, 2)}
+</metadata>`);
+  return { text: parts.join("\n"), isError };
+}
+var init_response_formatter = __esm({
+  "src/mcp-server/response-formatter.ts"() {
+    "use strict";
+  }
+});
+
 // src/mcp-server/server.ts
 var server_exports = {};
 __export(server_exports, {
@@ -1002,6 +1096,7 @@ var init_server = __esm({
     init_list_available_backends();
     init_backend_selector();
     init_logger();
+    init_response_formatter();
     spawnAgentsParallelInputShape = {
       agents: z5.array(spawnAgentInputSchema).min(1).max(10).describe(
         "Array of agent configurations to execute in parallel (1-10 agents)"
@@ -1018,7 +1113,7 @@ var init_server = __esm({
         this.backendSelector = new BackendSelector();
         this.server = new McpServer({
           name: "agentic-relay",
-          version: "0.8.0"
+          version: "0.9.1"
         });
         this.registerTools(this.server);
       }
@@ -1067,17 +1162,7 @@ var init_server = __esm({
                 this._childHttpUrl,
                 onProgress
               );
-              const isError = result.exitCode !== 0;
-              let text = isError ? `Error (exit ${result.exitCode}): ${result.stderr || result.stdout}` : `Session: ${result.sessionId}
-
-${result.stdout}`;
-              if (result.metadata) {
-                text += `
-
-<metadata>
-${JSON.stringify(result.metadata, null, 2)}
-</metadata>`;
-              }
+              const { text, isError } = formatSpawnAgentResponse(result);
               return {
                 content: [{ type: "text", text }],
                 isError
@@ -1122,15 +1207,7 @@ ${JSON.stringify(result.metadata, null, 2)}
                 this._childHttpUrl,
                 onProgress
               );
-              const isError = result.failureCount === result.totalCount;
-              let text = "";
-              if (result.hasConflicts) {
-                text += "\u26A0 FILE CONFLICTS DETECTED: Multiple agents modified the same files.\n";
-                text += `Conflicting files: ${result.conflicts.map((c) => c.path).join(", ")}
-
-`;
-              }
-              text += JSON.stringify(result, null, 2);
+              const { text, isError } = formatParallelResponse(result);
               return {
                 content: [{ type: "text", text }],
                 isError
@@ -1151,11 +1228,24 @@ ${JSON.stringify(result.metadata, null, 2)}
             failedResults: z5.array(z5.object({
               index: z5.number(),
               originalInput: spawnAgentInputSchema
-            })).min(1).describe("Array of failed results with their original input configurations")
+            })).min(1).describe("Array of failed results with their original input configurations"),
+            overrides: z5.object({
+              maxTurns: z5.number().optional(),
+              timeoutMs: z5.number().optional(),
+              preferredBackend: z5.enum(["claude", "codex", "gemini"]).optional()
+            }).optional().describe("Parameter overrides applied to all retried agents")
           },
           async (params) => {
             try {
-              const agents = params.failedResults.map((r) => r.originalInput);
+              const agents = params.failedResults.map((r) => {
+                const input = { ...r.originalInput };
+                if (params.overrides) {
+                  if (params.overrides.maxTurns !== void 0) input.maxTurns = params.overrides.maxTurns;
+                  if (params.overrides.timeoutMs !== void 0) input.timeoutMs = params.overrides.timeoutMs;
+                  if (params.overrides.preferredBackend !== void 0) input.preferredBackend = params.overrides.preferredBackend;
+                }
+                return input;
+              });
               const result = await executeSpawnAgentsParallel(
                 agents,
                 this.registry,
@@ -1166,8 +1256,7 @@ ${JSON.stringify(result.metadata, null, 2)}
                 this.backendSelector,
                 this._childHttpUrl
               );
-              const isError = result.failureCount === result.totalCount;
-              const text = JSON.stringify(result, null, 2);
+              const { text, isError } = formatParallelResponse(result);
               return {
                 content: [{ type: "text", text }],
                 isError
@@ -1269,6 +1358,7 @@ ${JSON.stringify(result.metadata, null, 2)}
       async start(options) {
         const transportType = options?.transport ?? "stdio";
         if (transportType === "stdio") {
+          redirectToStderr();
           logger.info("Starting agentic-relay MCP server (stdio transport)...");
           const transport = new StdioServerTransport();
           await this.server.connect(transport);
@@ -1331,7 +1421,7 @@ ${JSON.stringify(result.metadata, null, 2)}
           });
           const server = new McpServer({
             name: "agentic-relay",
-            version: "0.8.0"
+            version: "0.9.1"
           });
           this.registerTools(server);
           transport.onclose = () => {
@@ -1695,8 +1785,10 @@ var CLAUDE_NESTING_ENV_VARS = [
   "CLAUDE_CODE_SSE_PORT",
   "CLAUDE_CODE_ENTRYPOINT"
 ];
-var DEFAULT_CLAUDE_SDK_TIMEOUT_MS = 5 * 60 * 1e3;
-function getClaudeSdkTimeoutMs() {
+function resolveClaudeSdkTimeoutMs(flagsTimeoutMs) {
+  if (flagsTimeoutMs !== void 0 && flagsTimeoutMs > 0) {
+    return flagsTimeoutMs;
+  }
   const envVal = process.env["RELAY_CLAUDE_TIMEOUT_MS"];
   if (envVal) {
     const parsed = Number(envVal);
@@ -1704,7 +1796,7 @@ function getClaudeSdkTimeoutMs() {
       return parsed;
     }
   }
-  return DEFAULT_CLAUDE_SDK_TIMEOUT_MS;
+  return void 0;
 }
 var ClaudeAdapter = class extends BaseAdapter {
   id = "claude";
@@ -1743,9 +1835,9 @@ var ClaudeAdapter = class extends BaseAdapter {
     }
     const env = this.buildCleanEnv(flags);
     const permissionMode = this.getPermissionMode();
-    const timeoutMs = getClaudeSdkTimeoutMs();
+    const timeoutMs = resolveClaudeSdkTimeoutMs(flags.timeoutMs);
     const abortController = new AbortController();
-    const timer = setTimeout(() => abortController.abort(), timeoutMs);
+    const timer = timeoutMs !== void 0 ? setTimeout(() => abortController.abort(), timeoutMs) : void 0;
     try {
       const { query } = await loadClaudeSDK();
       const options = {
@@ -1770,7 +1862,16 @@ var ClaudeAdapter = class extends BaseAdapter {
       let sessionId = "";
       let isError = false;
       let errorMessages = [];
+      let totalInputTokens = 0;
+      let totalOutputTokens = 0;
       for await (const message of q) {
+        if (message.type === "assistant") {
+          const betaMessage = message.message;
+          if (betaMessage?.usage) {
+            totalInputTokens += betaMessage.usage.input_tokens ?? 0;
+            totalOutputTokens += betaMessage.usage.output_tokens ?? 0;
+          }
+        }
         if (message.type === "result") {
           sessionId = message.session_id;
           if (message.subtype === "success") {
@@ -1782,11 +1883,13 @@ var ClaudeAdapter = class extends BaseAdapter {
         }
       }
       logger.debug(`Claude SDK session: ${sessionId}`);
+      const hasTokenUsage = totalInputTokens > 0 || totalOutputTokens > 0;
       return {
         exitCode: isError ? 1 : 0,
         stdout: resultText,
         stderr: errorMessages.join("\n"),
-        ...sessionId ? { nativeSessionId: sessionId } : {}
+        ...sessionId ? { nativeSessionId: sessionId } : {},
+        ...hasTokenUsage ? { tokenUsage: { inputTokens: totalInputTokens, outputTokens: totalOutputTokens } } : {}
       };
     } catch (error) {
       if (abortController.signal.aborted) {
@@ -1802,7 +1905,7 @@ var ClaudeAdapter = class extends BaseAdapter {
         stderr: error instanceof Error ? error.message : String(error)
       };
     } finally {
-      clearTimeout(timer);
+      if (timer !== void 0) clearTimeout(timer);
     }
   }
   async *executeStreaming(flags) {
@@ -1811,9 +1914,9 @@ var ClaudeAdapter = class extends BaseAdapter {
     }
     const env = this.buildCleanEnv(flags);
     const permissionMode = this.getPermissionMode();
-    const timeoutMs = getClaudeSdkTimeoutMs();
+    const timeoutMs = resolveClaudeSdkTimeoutMs(flags.timeoutMs);
     const abortController = new AbortController();
-    const timer = setTimeout(() => abortController.abort(), timeoutMs);
+    const timer = timeoutMs !== void 0 ? setTimeout(() => abortController.abort(), timeoutMs) : void 0;
     try {
       const { query } = await loadClaudeSDK();
       const options = {
@@ -1888,13 +1991,13 @@ var ClaudeAdapter = class extends BaseAdapter {
         result: { exitCode: 1, stdout: "", stderr: errorMessage }
       };
     } finally {
-      clearTimeout(timer);
+      if (timer !== void 0) clearTimeout(timer);
     }
   }
   async continueSession(nativeSessionId, prompt) {
-    const timeoutMs = getClaudeSdkTimeoutMs();
+    const timeoutMs = resolveClaudeSdkTimeoutMs();
     const abortController = new AbortController();
-    const timer = setTimeout(() => abortController.abort(), timeoutMs);
+    const timer = timeoutMs !== void 0 ? setTimeout(() => abortController.abort(), timeoutMs) : void 0;
     try {
       const { query } = await loadClaudeSDK();
       const permissionMode = this.getPermissionMode();
@@ -1940,7 +2043,7 @@ var ClaudeAdapter = class extends BaseAdapter {
         stderr: error instanceof Error ? error.message : String(error)
       };
     } finally {
-      clearTimeout(timer);
+      if (timer !== void 0) clearTimeout(timer);
     }
   }
   async resumeSession(sessionId, flags) {
@@ -4266,7 +4369,7 @@ function createVersionCommand(registry2) {
       description: "Show relay and backend versions"
     },
     async run() {
-      const relayVersion = "0.8.0";
+      const relayVersion = "0.9.1";
       console.log(`agentic-relay v${relayVersion}`);
       console.log("");
       console.log("Backends:");
@@ -4616,7 +4719,7 @@ void configManager.getConfig().then((config) => {
 var main = defineCommand10({
   meta: {
     name: "relay",
-    version: "0.8.0",
+    version: "0.9.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": "0.8.0",
+  "version": "0.9.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",