@rk0429/agentic-relay 0.12.0 → 0.12.2

package/dist/relay.mjs

@@ -46,6 +46,129 @@ var init_logger = __esm({
   }
 });
 
+// src/mcp-server/deferred-cleanup-task-store.ts
+import { isTerminal } from "@modelcontextprotocol/sdk/experimental/tasks/interfaces.js";
+import { randomBytes } from "crypto";
+var DeferredCleanupTaskStore;
+var init_deferred_cleanup_task_store = __esm({
+  "src/mcp-server/deferred-cleanup-task-store.ts"() {
+    "use strict";
+    DeferredCleanupTaskStore = class {
+      tasks = /* @__PURE__ */ new Map();
+      cleanupTimers = /* @__PURE__ */ new Map();
+      generateTaskId() {
+        return randomBytes(16).toString("hex");
+      }
+      async createTask(taskParams, requestId, request, _sessionId) {
+        const taskId = this.generateTaskId();
+        if (this.tasks.has(taskId)) {
+          throw new Error(`Task with ID ${taskId} already exists`);
+        }
+        const actualTtl = taskParams.ttl ?? null;
+        const createdAt = (/* @__PURE__ */ new Date()).toISOString();
+        const task = {
+          taskId,
+          status: "working",
+          ttl: actualTtl,
+          createdAt,
+          lastUpdatedAt: createdAt,
+          pollInterval: taskParams.pollInterval ?? 1e3
+        };
+        this.tasks.set(taskId, { task, request, requestId });
+        return { ...task };
+      }
+      async getTask(taskId, _sessionId) {
+        const stored = this.tasks.get(taskId);
+        return stored ? { ...stored.task } : null;
+      }
+      async storeTaskResult(taskId, status, result, _sessionId) {
+        const stored = this.tasks.get(taskId);
+        if (!stored) {
+          throw new Error(`Task with ID ${taskId} not found`);
+        }
+        if (isTerminal(stored.task.status)) {
+          throw new Error(
+            `Cannot store result for task ${taskId} in terminal status '${stored.task.status}'. Task results can only be stored once.`
+          );
+        }
+        stored.result = result;
+        stored.task.status = status;
+        stored.task.lastUpdatedAt = (/* @__PURE__ */ new Date()).toISOString();
+        this.scheduleCleanup(taskId, stored.task.ttl);
+      }
+      async getTaskResult(taskId, _sessionId) {
+        const stored = this.tasks.get(taskId);
+        if (!stored) {
+          throw new Error(`Task with ID ${taskId} not found`);
+        }
+        if (!stored.result) {
+          throw new Error(`Task ${taskId} has no result stored`);
+        }
+        return stored.result;
+      }
+      async updateTaskStatus(taskId, status, statusMessage, _sessionId) {
+        const stored = this.tasks.get(taskId);
+        if (!stored) {
+          throw new Error(`Task with ID ${taskId} not found`);
+        }
+        if (isTerminal(stored.task.status)) {
+          throw new Error(
+            `Cannot update task ${taskId} from terminal status '${stored.task.status}'.`
+          );
+        }
+        stored.task.status = status;
+        if (statusMessage) {
+          stored.task.statusMessage = statusMessage;
+        }
+        stored.task.lastUpdatedAt = (/* @__PURE__ */ new Date()).toISOString();
+        if (isTerminal(status)) {
+          this.scheduleCleanup(taskId, stored.task.ttl);
+        }
+      }
+      async listTasks(cursor, _sessionId) {
+        const PAGE_SIZE = 10;
+        const allTaskIds = Array.from(this.tasks.keys());
+        let startIndex = 0;
+        if (cursor) {
+          const cursorIndex = allTaskIds.indexOf(cursor);
+          if (cursorIndex >= 0) {
+            startIndex = cursorIndex + 1;
+          } else {
+            throw new Error(`Invalid cursor: ${cursor}`);
+          }
+        }
+        const pageTaskIds = allTaskIds.slice(startIndex, startIndex + PAGE_SIZE);
+        const tasks = pageTaskIds.map((id) => {
+          const stored = this.tasks.get(id);
+          return { ...stored.task };
+        });
+        const nextCursor = startIndex + PAGE_SIZE < allTaskIds.length ? pageTaskIds[pageTaskIds.length - 1] : void 0;
+        return { tasks, nextCursor };
+      }
+      /** Cleanup all timers (for testing or graceful shutdown) */
+      cleanup() {
+        for (const timer of this.cleanupTimers.values()) {
+          clearTimeout(timer);
+        }
+        this.cleanupTimers.clear();
+        this.tasks.clear();
+      }
+      scheduleCleanup(taskId, ttl) {
+        if (!ttl) return;
+        const existingTimer = this.cleanupTimers.get(taskId);
+        if (existingTimer) {
+          clearTimeout(existingTimer);
+        }
+        const timer = setTimeout(() => {
+          this.tasks.delete(taskId);
+          this.cleanupTimers.delete(taskId);
+        }, ttl);
+        this.cleanupTimers.set(taskId, timer);
+      }
+    };
+  }
+});
+
 // src/mcp-server/recursion-guard.ts
 import { createHash } from "crypto";
 var RecursionGuard;
@@ -658,27 +781,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 +1135,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",
@@ -1137,13 +1281,12 @@ __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();
+  const taskStore = new DeferredCleanupTaskStore();
   return {
     capabilities: { tasks: { requests: { tools: { call: {} } } } },
     taskStore,
@@ -1155,6 +1298,7 @@ var spawnAgentsParallelInputShape, MAX_CHILD_HTTP_SESSIONS, RelayMCPServer;
 var init_server = __esm({
   "src/mcp-server/server.ts"() {
     "use strict";
+    init_deferred_cleanup_task_store();
     init_recursion_guard();
     init_spawn_agent();
     init_spawn_agents_parallel();
@@ -1180,7 +1324,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.2" },
           createMcpServerOptions()
         );
         this.registerTools(this.server);
@@ -1296,7 +1440,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 +1454,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 +1480,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 +1542,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 +1572,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 +1688,7 @@ var init_server = __esm({
             sessionIdGenerator: () => randomUUID()
           });
           const server = new McpServer(
-            { name: "agentic-relay", version: "0.12.0" },
+            { name: "agentic-relay", version: "0.12.2" },
             createMcpServerOptions()
           );
           this.registerTools(server);
@@ -3414,7 +3560,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 +3608,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 +4001,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 +4041,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 +4057,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 +4640,7 @@ function createVersionCommand(registry2) {
       description: "Show relay and backend versions"
     },
     async run() {
-      const relayVersion = "0.12.0";
+      const relayVersion = "0.12.2";
       console.log(`agentic-relay v${relayVersion}`);
       console.log("");
       console.log("Backends:");
@@ -4845,7 +4990,7 @@ void configManager.getConfig().then((config) => {
 var main = defineCommand10({
   meta: {
     name: "relay",
-    version: "0.12.0",
+    version: "0.12.2",
     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.2",
   "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",