@rk0429/agentic-relay 0.12.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",
@@ -1180,7 +1201,7 @@ var init_server = __esm({
         this.guard = new RecursionGuard(guardConfig);
         this.backendSelector = new BackendSelector();
         this.server = new McpServer(
-          { name: "agentic-relay", version: "0.12.0" },
+          { name: "agentic-relay", version: "0.12.1" },
           createMcpServerOptions()
         );
         this.registerTools(this.server);
@@ -1296,7 +1317,7 @@ var init_server = __esm({
         server.experimental.tasks.registerToolTask(
           "spawn_agent",
           {
-            description: "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.",
+            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" }
           },
@@ -1310,18 +1331,19 @@ var init_server = __esm({
               return { task };
             },
             getTask: async (_params, extra) => {
-              const task = await extra.taskStore.getTask(extra.taskId);
-              return { task: task ?? void 0 };
+              return await extra.taskStore.getTask(extra.taskId);
             },
             getTaskResult: async (_params, extra) => {
-              return await extra.taskStore.getTaskResult(extra.taskId);
+              return await extra.taskStore.getTaskResult(
+                extra.taskId
+              );
             }
           }
         );
         server.experimental.tasks.registerToolTask(
           "spawn_agents_parallel",
           {
-            description: "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.",
+            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" }
           },
@@ -1335,11 +1357,12 @@ var init_server = __esm({
               return { task };
             },
             getTask: async (_params, extra) => {
-              const task = await extra.taskStore.getTask(extra.taskId);
-              return { task: task ?? void 0 };
+              return await extra.taskStore.getTask(extra.taskId);
             },
             getTaskResult: async (_params, extra) => {
-              return await extra.taskStore.getTaskResult(extra.taskId);
+              return await extra.taskStore.getTaskResult(
+                extra.taskId
+              );
             }
           }
         );
@@ -1396,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 {
@@ -1426,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 {
@@ -1542,7 +1565,7 @@ var init_server = __esm({
             sessionIdGenerator: () => randomUUID()
           });
           const server = new McpServer(
-            { name: "agentic-relay", version: "0.12.0" },
+            { name: "agentic-relay", version: "0.12.1" },
             createMcpServerOptions()
           );
           this.registerTools(server);
@@ -3414,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") {
@@ -3461,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") {
@@ -3853,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) {
@@ -3894,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, {
@@ -3911,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, {
@@ -4495,7 +4517,7 @@ function createVersionCommand(registry2) {
       description: "Show relay and backend versions"
     },
     async run() {
-      const relayVersion = "0.12.0";
+      const relayVersion = "0.12.1";
       console.log(`agentic-relay v${relayVersion}`);
       console.log("");
       console.log("Backends:");
@@ -4845,7 +4867,7 @@ void configManager.getConfig().then((config) => {
 var main = defineCommand10({
   meta: {
     name: "relay",
-    version: "0.12.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.12.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",