@rk0429/agentic-relay 0.11.0 → 0.12.1

package/dist/relay.mjs

@@ -658,27 +658,45 @@ var init_spawn_agent = __esm({
     init_recursion_guard();
     init_logger();
     spawnAgentInputSchema = z2.object({
-      backend: z2.enum(["claude", "codex", "gemini"]),
-      prompt: z2.string(),
-      agent: z2.string().optional(),
-      systemPrompt: z2.string().optional(),
-      resumeSessionId: z2.string().optional(),
-      model: z2.string().optional(),
-      maxTurns: z2.number().optional(),
+      backend: z2.enum(["claude", "codex", "gemini"]).describe(
+        "Required fallback backend. Overridden by automatic selection when BackendSelector is active (priority: preferredBackend > agentType mapping > taskType mapping > default)."
+      ),
+      prompt: z2.string().describe(
+        "The task instruction for the sub-agent. Be specific and include all necessary context for autonomous execution."
+      ),
+      agent: z2.string().optional().describe(
+        "Agent type identifier (e.g., 'coder', 'researcher', 'documenter', 'software-engineer'). Affects backend auto-selection: coder/researcher/software-engineer/devops-engineer\u2192codex, documenter\u2192claude. Also used to resolve agentDefinition files from .agents/agents/<agent>.md."
+      ),
+      systemPrompt: z2.string().optional().describe(
+        "Custom system prompt prepended to the agent's context. Use agentDefinition instead when a .md definition file exists."
+      ),
+      resumeSessionId: z2.string().optional().describe(
+        "Relay session ID to resume. Enables multi-turn continuation of a previous agent execution."
+      ),
+      model: z2.string().optional().describe(
+        "Model to use (e.g., 'opus', 'sonnet', 'o3'). Passed to the backend CLI. Model availability varies by backend."
+      ),
+      maxTurns: z2.number().optional().describe(
+        "Maximum agentic turns (tool-use cycles). Limits execution depth to prevent runaway agents."
+      ),
       skillContext: z2.object({
         skillPath: z2.string().describe("Path to the skill directory (e.g., '.agents/skills/software-engineer/')"),
-        subskill: z2.string().optional().describe("Specific subskill to activate")
-      }).optional().describe("Skill context to inject into the subagent's system prompt"),
+        subskill: z2.string().optional().describe("Specific subskill to activate within the skill")
+      }).optional().describe("Skill context to inject into the sub-agent's system prompt. Loads SKILL.md/SUBSKILL.md content."),
       agentDefinition: z2.object({
-        definitionPath: z2.string().describe("Path to the agent definition file (e.g., '.claude/agents/software-engineer.md')")
-      }).optional().describe("Agent definition file to inject into the sub-agent's system prompt"),
-      preferredBackend: z2.enum(["claude", "codex", "gemini"]).optional().describe("Preferred backend override. Takes priority over automatic selection based on agent/task type."),
-      taskType: z2.enum(["code-writing", "code-review", "document-writing", "document-review", "research", "mixed"]).optional().describe("Task type hint for automatic backend selection when preferredBackend is not specified. code-writing\u2192codex, code-review\u2192claude, document-writing\u2192claude, document-review\u2192codex, research\u2192codex, mixed\u2192claude."),
+        definitionPath: z2.string().describe("Path to the agent definition .md file (e.g., '.agents/agents/coder.md')")
+      }).optional().describe("Agent definition file to inject into the sub-agent's system prompt as <agent-definition> context."),
+      preferredBackend: z2.enum(["claude", "codex", "gemini"]).optional().describe(
+        "Preferred backend override. Takes highest priority in backend selection. Use when the automatic agentType/taskType mapping does not match your needs."
+      ),
+      taskType: z2.enum(["code-writing", "code-review", "document-writing", "document-review", "research", "mixed"]).optional().describe(
+        "Task type hint for automatic backend selection (priority 3, after preferredBackend and agentType). Mapping: code-writing\u2192codex, code-review\u2192claude, document-writing\u2192claude, document-review\u2192codex, research\u2192codex, mixed\u2192claude."
+      ),
       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")
+      label: z2.string().optional().describe("Human-readable label for identifying this agent in parallel results and logs.")
     });
   }
 });
@@ -994,7 +1012,10 @@ var init_backend_selector = __esm({
       "skill-developer": "codex",
       "security-auditor": "codex",
       "analytics-engineer": "codex",
-      "payments-billing": "codex"
+      "payments-billing": "codex",
+      "coder": "codex",
+      "researcher": "codex",
+      "documenter": "claude"
     };
     TASK_TYPE_TO_BACKEND_MAP = {
       "code-writing": "codex",
@@ -1047,6 +1068,24 @@ var init_backend_selector = __esm({
   }
 });
 
+// src/types/mcp.ts
+var DEFAULT_TASK_TTL, DEFAULT_POLL_INTERVAL;
+var init_mcp = __esm({
+  "src/types/mcp.ts"() {
+    "use strict";
+    DEFAULT_TASK_TTL = 5 * 60 * 1e3;
+    DEFAULT_POLL_INTERVAL = 3e3;
+  }
+});
+
+// src/types/index.ts
+var init_types = __esm({
+  "src/types/index.ts"() {
+    "use strict";
+    init_mcp();
+  }
+});
+
 // src/mcp-server/response-formatter.ts
 function formatSpawnAgentResponse(result) {
   const isError = result.exitCode !== 0;
@@ -1119,9 +1158,20 @@ __export(server_exports, {
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import { InMemoryTaskStore } from "@modelcontextprotocol/sdk/experimental/tasks/stores/in-memory.js";
+import { InMemoryTaskMessageQueue } from "@modelcontextprotocol/sdk/experimental/tasks/stores/in-memory.js";
 import { createServer } from "http";
 import { randomUUID } from "crypto";
 import { z as z5 } from "zod";
+function createMcpServerOptions() {
+  const taskStore = new InMemoryTaskStore();
+  return {
+    capabilities: { tasks: { requests: { tools: { call: {} } } } },
+    taskStore,
+    taskMessageQueue: new InMemoryTaskMessageQueue(),
+    defaultTaskPollInterval: DEFAULT_POLL_INTERVAL
+  };
+}
 var spawnAgentsParallelInputShape, MAX_CHILD_HTTP_SESSIONS, RelayMCPServer;
 var init_server = __esm({
   "src/mcp-server/server.ts"() {
@@ -1134,6 +1184,7 @@ var init_server = __esm({
     init_list_available_backends();
     init_backend_selector();
     init_logger();
+    init_types();
     init_response_formatter();
     spawnAgentsParallelInputShape = {
       agents: z5.array(spawnAgentInputSchema).min(1).max(10).describe(
@@ -1149,10 +1200,10 @@ var init_server = __esm({
         this.contextMonitor = contextMonitor2;
         this.guard = new RecursionGuard(guardConfig);
         this.backendSelector = new BackendSelector();
-        this.server = new McpServer({
-          name: "agentic-relay",
-          version: "0.11.0"
-        });
+        this.server = new McpServer(
+          { name: "agentic-relay", version: "0.12.1" },
+          createMcpServerOptions()
+        );
         this.registerTools(this.server);
       }
       server;
@@ -1168,94 +1219,150 @@ var init_server = __esm({
       get childHttpServer() {
         return this._childHttpServer;
       }
-      registerTools(server) {
-        server.tool(
-          "spawn_agent",
-          "Spawn a sub-agent on the specified backend CLI (Claude Code, Codex CLI, or Gemini CLI). The agent executes the given prompt in non-interactive mode and returns the result. Use 'agent' for named agent configurations (Claude only), 'systemPrompt' for custom role instructions (all backends), 'skillContext' to inject a skill definition (SKILL.md/SUBSKILL.md), 'agentDefinition' to inject an agent definition file into the sub-agent's system prompt, 'preferredBackend' to override automatic backend selection, or 'taskType' to hint at the task nature for backend selection.",
-          spawnAgentInputSchema.shape,
-          async (params, extra) => {
+      /**
+       * Run spawn_agent in the background and store the result in taskStore.
+       * Fire-and-forget: errors are caught and stored as failed task results.
+       */
+      runSpawnAgentInBackground(taskId, params, extra) {
+        const run = async () => {
+          try {
+            const result = await executeSpawnAgent(
+              params,
+              this.registry,
+              this.sessionManager,
+              this.guard,
+              this.hooksEngine,
+              this.contextMonitor,
+              this.backendSelector,
+              this._childHttpUrl
+            );
+            const { text, isError } = formatSpawnAgentResponse(result);
+            const callToolResult = {
+              content: [{ type: "text", text }],
+              isError
+            };
+            await extra.taskStore.storeTaskResult(
+              taskId,
+              "completed",
+              callToolResult
+            );
+          } catch (outerError) {
             try {
-              const onProgress = (progress) => {
-                const progressToken = params._meta ? params._meta.progressToken : void 0;
-                if (progressToken !== void 0) {
-                  void extra.sendNotification({
-                    method: "notifications/progress",
-                    params: {
-                      progressToken,
-                      progress: progress.percent ?? 0,
-                      total: 100,
-                      message: progress.stage
-                    }
-                  });
+              const message = outerError instanceof Error ? outerError.message : String(outerError);
+              await extra.taskStore.storeTaskResult(
+                taskId,
+                "failed",
+                {
+                  content: [{ type: "text", text: `Error: ${message}` }],
+                  isError: true
                 }
-              };
-              const result = await executeSpawnAgent(
-                params,
-                this.registry,
-                this.sessionManager,
-                this.guard,
-                this.hooksEngine,
-                this.contextMonitor,
-                this.backendSelector,
-                this._childHttpUrl,
-                onProgress
               );
-              const { text, isError } = formatSpawnAgentResponse(result);
-              return {
-                content: [{ type: "text", text }],
-                isError
-              };
-            } catch (error) {
-              const message = error instanceof Error ? error.message : String(error);
-              return {
-                content: [{ type: "text", text: `Error: ${message}` }],
-                isError: true
-              };
+            } catch (storeError) {
+              logger.error(
+                `Failed to store task result for ${taskId}: ${storeError instanceof Error ? storeError.message : String(storeError)}`
+              );
             }
           }
-        );
-        server.tool(
-          "spawn_agents_parallel",
-          "Spawn multiple sub-agents in parallel across available backends. Each agent entry accepts the same parameters as spawn_agent. All agents are executed concurrently via Promise.allSettled, and results are returned as an array with per-agent status. RecursionGuard batch pre-validation ensures the entire batch fits within call limits before execution begins. Failed results include 'originalInput' for retry via retry_failed_agents.",
-          spawnAgentsParallelInputShape,
-          async (params, extra) => {
+        };
+        void run();
+      }
+      /**
+       * Run spawn_agents_parallel in the background and store the result in taskStore.
+       * Fire-and-forget: errors are caught and stored as failed task results.
+       */
+      runSpawnAgentsParallelInBackground(taskId, agents, extra) {
+        const run = async () => {
+          try {
+            const result = await executeSpawnAgentsParallel(
+              agents,
+              this.registry,
+              this.sessionManager,
+              this.guard,
+              this.hooksEngine,
+              this.contextMonitor,
+              this.backendSelector,
+              this._childHttpUrl
+            );
+            const { text, isError } = formatParallelResponse(result);
+            const callToolResult = {
+              content: [{ type: "text", text }],
+              isError
+            };
+            await extra.taskStore.storeTaskResult(
+              taskId,
+              "completed",
+              callToolResult
+            );
+          } catch (outerError) {
             try {
-              const onProgress = (progress) => {
-                const progressToken = params._meta ? params._meta.progressToken : void 0;
-                if (progressToken !== void 0) {
-                  void extra.sendNotification({
-                    method: "notifications/progress",
-                    params: {
-                      progressToken,
-                      progress: progress.percent ?? 0,
-                      total: 100,
-                      message: progress.stage
-                    }
-                  });
+              const message = outerError instanceof Error ? outerError.message : String(outerError);
+              await extra.taskStore.storeTaskResult(
+                taskId,
+                "failed",
+                {
+                  content: [{ type: "text", text: `Error: ${message}` }],
+                  isError: true
                 }
-              };
-              const result = await executeSpawnAgentsParallel(
-                params.agents,
-                this.registry,
-                this.sessionManager,
-                this.guard,
-                this.hooksEngine,
-                this.contextMonitor,
-                this.backendSelector,
-                this._childHttpUrl,
-                onProgress
               );
-              const { text, isError } = formatParallelResponse(result);
-              return {
-                content: [{ type: "text", text }],
-                isError
-              };
-            } catch (error) {
-              const message = error instanceof Error ? error.message : String(error);
-              return {
-                content: [{ type: "text", text: `Error: ${message}` }],
-                isError: true
-              };
+            } catch (storeError) {
+              logger.error(
+                `Failed to store parallel task result for ${taskId}: ${storeError instanceof Error ? storeError.message : String(storeError)}`
+              );
+            }
+          }
+        };
+        void run();
+      }
+      registerTools(server) {
+        server.experimental.tasks.registerToolTask(
+          "spawn_agent",
+          {
+            description: "Spawn a sub-agent on a backend CLI (Claude Code, Codex CLI, or Gemini CLI). The agent executes the given prompt in non-interactive mode and returns the result. Backend is auto-selected by priority: preferredBackend > agentType mapping (coder/researcher\u2192codex, documenter\u2192claude) > taskType mapping > default (claude). Use 'agentDefinition' to inject an agent .md file, 'skillContext' for a SKILL.md, or 'systemPrompt' for custom instructions.",
+            inputSchema: spawnAgentInputSchema.shape,
+            execution: { taskSupport: "optional" }
+          },
+          {
+            createTask: async (params, extra) => {
+              const task = await extra.taskStore.createTask({
+                ttl: DEFAULT_TASK_TTL,
+                pollInterval: DEFAULT_POLL_INTERVAL
+              });
+              this.runSpawnAgentInBackground(task.taskId, params, extra);
+              return { task };
+            },
+            getTask: async (_params, extra) => {
+              return await extra.taskStore.getTask(extra.taskId);
+            },
+            getTaskResult: async (_params, extra) => {
+              return await extra.taskStore.getTaskResult(
+                extra.taskId
+              );
+            }
+          }
+        );
+        server.experimental.tasks.registerToolTask(
+          "spawn_agents_parallel",
+          {
+            description: "Spawn multiple sub-agents in parallel across available backends. Use this when you have 2+ independent tasks that can execute concurrently. Each agent entry accepts the same parameters as spawn_agent. Results are returned as an array with per-agent status (success/failure). RecursionGuard batch pre-validation ensures the batch fits within call limits. Failed results include 'originalInput' for retry via retry_failed_agents.",
+            inputSchema: spawnAgentsParallelInputShape,
+            execution: { taskSupport: "optional" }
+          },
+          {
+            createTask: async (params, extra) => {
+              const task = await extra.taskStore.createTask({
+                ttl: DEFAULT_TASK_TTL,
+                pollInterval: DEFAULT_POLL_INTERVAL
+              });
+              this.runSpawnAgentsParallelInBackground(task.taskId, params.agents, extra);
+              return { task };
+            },
+            getTask: async (_params, extra) => {
+              return await extra.taskStore.getTask(extra.taskId);
+            },
+            getTaskResult: async (_params, extra) => {
+              return await extra.taskStore.getTaskResult(
+                extra.taskId
+              );
             }
           }
         );
@@ -1312,8 +1419,8 @@ var init_server = __esm({
           "list_sessions",
           "List relay sessions, optionally filtered by backend.",
           {
-            backend: z5.enum(["claude", "codex", "gemini"]).optional(),
-            limit: z5.number().optional()
+            backend: z5.enum(["claude", "codex", "gemini"]).optional().describe("Filter sessions by backend type."),
+            limit: z5.number().optional().describe("Maximum number of sessions to return. Default: 10.")
           },
           async (params) => {
             try {
@@ -1342,7 +1449,7 @@ var init_server = __esm({
           "get_context_status",
           "Get the context usage status of a relay session. Returns usage data from ContextMonitor when available, otherwise estimated values.",
           {
-            sessionId: z5.string()
+            sessionId: z5.string().describe("Relay session ID to query context usage for.")
           },
           async (params) => {
             try {
@@ -1457,10 +1564,10 @@ var init_server = __esm({
           const transport = new StreamableHTTPServerTransport({
             sessionIdGenerator: () => randomUUID()
           });
-          const server = new McpServer({
-            name: "agentic-relay",
-            version: "0.11.0"
-          });
+          const server = new McpServer(
+            { name: "agentic-relay", version: "0.12.1" },
+            createMcpServerOptions()
+          );
           this.registerTools(server);
           transport.onclose = () => {
             const sid2 = transport.sessionId;
@@ -3330,7 +3437,8 @@ var HooksEngine = class _HooksEngine {
         const message = error instanceof Error ? error.message : String(error);
         if (strategy === "abort") {
           throw new Error(
-            `Hook "${def.command}" failed (abort): ${message}`
+            `Hook "${def.command}" failed (abort): ${message}`,
+            { cause: error }
           );
         }
         if (strategy === "warn") {
@@ -3377,7 +3485,8 @@ var HooksEngine = class _HooksEngine {
         const message = error instanceof Error ? error.message : String(error);
         if (strategy === "abort") {
           throw new Error(
-            `Hook "${def.command}" failed (abort): ${message}`
+            `Hook "${def.command}" failed (abort): ${message}`,
+            { cause: error }
           );
         }
         if (strategy === "warn") {
@@ -3769,7 +3878,6 @@ function createBackendCommand(backendId, registry2, sessionManager2, hooksEngine
       try {
         if (flags.prompt) {
           logger.debug(`Executing prompt on ${backendId}`);
-          let nativeSessionId;
           if (adapter.executeStreaming) {
             for await (const event of adapter.executeStreaming(flags)) {
               switch (event.type) {
@@ -3810,7 +3918,6 @@ function createBackendCommand(backendId, registry2, sessionManager2, hooksEngine
                 }
                 case "done":
                   process.exitCode = event.result.exitCode;
-                  nativeSessionId = event.nativeSessionId;
                   if (event.nativeSessionId && sessionManager2 && relaySessionId) {
                     try {
                       await sessionManager2.update(relaySessionId, {
@@ -3827,7 +3934,6 @@ function createBackendCommand(backendId, registry2, sessionManager2, hooksEngine
             if (result.stdout) process.stdout.write(result.stdout);
             if (result.stderr) process.stderr.write(result.stderr);
             process.exitCode = result.exitCode;
-            nativeSessionId = result.nativeSessionId;
             if (result.nativeSessionId && sessionManager2 && relaySessionId) {
               try {
                 await sessionManager2.update(relaySessionId, {
@@ -4411,7 +4517,7 @@ function createVersionCommand(registry2) {
       description: "Show relay and backend versions"
     },
     async run() {
-      const relayVersion = "0.11.0";
+      const relayVersion = "0.12.1";
       console.log(`agentic-relay v${relayVersion}`);
       console.log("");
       console.log("Backends:");
@@ -4761,7 +4867,7 @@ void configManager.getConfig().then((config) => {
 var main = defineCommand10({
   meta: {
     name: "relay",
-    version: "0.11.0",
+    version: "0.12.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.11.0",
+  "version": "0.12.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",