@rk0429/agentic-relay 0.1.2 → 0.3.0

package/README.md

@@ -1,5 +1,10 @@
 # agentic-relay
 
+[![CI](https://github.com/RK0429/agentic-relay/actions/workflows/ci.yml/badge.svg)](https://github.com/RK0429/agentic-relay/actions/workflows/ci.yml)
+[![npm version](https://img.shields.io/npm/v/@rk0429/agentic-relay)](https://www.npmjs.com/package/@rk0429/agentic-relay)
+[![License: Apache-2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
+[![Node.js](https://img.shields.io/badge/node-%3E%3D22-brightgreen)](https://nodejs.org/)
+
 A unified CLI that brings Claude Code, Codex CLI, and Gemini CLI under a single interface -- solving tool fragmentation, enabling multi-layer sub-agent orchestration via MCP, and providing proactive context window monitoring.
 
 ## Why agentic-relay?
@@ -94,7 +99,9 @@ relay mcp list              # List MCP servers
 relay mcp add <name> -- CMD # Add MCP server
 relay mcp remove <name>     # Remove MCP server
 relay mcp sync              # Sync MCP config to backends
-relay mcp serve             # Start relay as MCP server (stdio)
+relay mcp serve                              # Start as MCP server (stdio, default)
+relay mcp serve --transport http             # Start as MCP server (HTTP)
+relay mcp serve --transport http --port 8080 # Custom port
 ```
 
 ## Configuration
@@ -144,9 +151,10 @@ Example configuration:
 | `RELAY_LOG_LEVEL` | Log level (debug/info/warn/error) | `info` |
 | `RELAY_MAX_DEPTH` | Max recursion depth in MCP server mode | `5` |
 | `RELAY_CONTEXT_THRESHOLD` | Context warning threshold (%) | `75` |
-| `ANTHROPIC_API_KEY` | Passed through to Claude Code | -- |
-| `OPENAI_API_KEY` | Passed through to Codex CLI | -- |
-| `GEMINI_API_KEY` | Passed through to Gemini CLI | -- |
+| `RELAY_CLAUDE_PERMISSION_MODE` | Claude permission mode (`bypassPermissions` or `default`) | `bypassPermissions` |
+| `ANTHROPIC_API_KEY` | Passed through to Claude Code (optional with subscription) | -- |
+| `OPENAI_API_KEY` | Passed through to Codex CLI (optional with subscription) | -- |
+| `GEMINI_API_KEY` | Passed through to Gemini CLI (optional with subscription) | -- |
 
 ## MCP Server Mode
 
@@ -199,10 +207,10 @@ sequenceDiagram
     User->>Parent: Task request
     Parent->>Relay: spawn_agent(codex, prompt)
     Note over Relay: RecursionGuard check<br>depth=1, calls=1
-    Relay->>Child: relay codex -p "prompt"<br>RELAY_DEPTH=1
+    Relay->>Child: Codex SDK thread.run("prompt")<br>RELAY_DEPTH=1
     Child->>Relay2: spawn_agent(gemini, sub-prompt)
     Note over Relay2: RecursionGuard check<br>depth=2, calls=1
-    Relay2->>Grandchild: relay gemini -p "sub-prompt"<br>RELAY_DEPTH=2
+    Relay2->>Grandchild: gemini -p "sub-prompt"<br>RELAY_DEPTH=2
     Grandchild-->>Relay2: Result
     Relay2-->>Child: Result
     Child-->>Relay: Result
@@ -229,6 +237,14 @@ graph TD
 
 Each backend CLI has different flags, output formats, and session handling. The adapter layer normalizes these differences behind a common `BackendAdapter` interface. Adding a new backend means implementing this interface and registering it with the `AdapterRegistry`.
 
+Non-interactive execution uses official SDKs where available:
+
+| Backend | Non-interactive (`-p`) | Interactive | Session listing |
+|---|---|---|---|
+| Claude Code | Agent SDK `query()` | CLI spawn | Agent SDK `listSessions()` |
+| Codex CLI | Codex SDK `thread.run()` | CLI spawn | -- |
+| Gemini CLI | CLI spawn | CLI spawn | CLI `--list-sessions` |
+
 ### Hooks Engine
 
 An event-driven hook system that executes external commands via stdin/stdout JSON pipes.
@@ -296,11 +312,13 @@ src/
 - **Package manager**: pnpm
 - **CLI framework**: citty
 - **Bundler**: tsup (esbuild-based)
+- **Backend SDKs**: @anthropic-ai/claude-agent-sdk, @openai/codex-sdk
 - **MCP**: @modelcontextprotocol/sdk
-- **Process management**: execa
+- **Process management**: execa (interactive modes, Gemini CLI)
 - **Validation**: zod
 - **Logging**: consola
-- **Testing**: vitest (274 tests across 18 files)
+- **Testing**: vitest (352 tests across 18 files)
+- **Coverage**: @vitest/coverage-v8
 
 ## License
 

package/dist/relay.mjs

@@ -48,6 +48,7 @@ var ProcessManager = class {
       stdio: "inherit",
       cwd: options?.cwd,
       env: options?.env,
+      extendEnv: options?.env ? false : true,
       timeout: options?.timeout,
       reject: false
     };
@@ -61,10 +62,13 @@ var ProcessManager = class {
   }
   async execute(command, args, options) {
     logger.debug(`Executing: ${command} ${args.join(" ")}`);
+    const stdinMode = options?.stdinMode ?? "pipe";
+    const stdio = stdinMode === "pipe" ? "pipe" : [stdinMode, "pipe", "pipe"];
     const execaOptions = {
-      stdio: "pipe",
+      stdio,
       cwd: options?.cwd,
       env: options?.env,
+      extendEnv: options?.env ? false : true,
       timeout: options?.timeout,
       reject: false
     };
@@ -246,6 +250,15 @@ function mapCommonToNative(backendId, flags) {
 }
 
 // src/adapters/claude-adapter.ts
+import {
+  query,
+  listSessions
+} from "@anthropic-ai/claude-agent-sdk";
+var CLAUDE_NESTING_ENV_VARS = [
+  "CLAUDECODE",
+  "CLAUDE_CODE_SSE_PORT",
+  "CLAUDE_CODE_ENTRYPOINT"
+];
 var ClaudeAdapter = class extends BaseAdapter {
   id = "claude";
   command = "claude";
@@ -256,26 +269,171 @@ var ClaudeAdapter = class extends BaseAdapter {
   }
   async startInteractive(flags) {
     const { args } = this.mapFlags(flags);
-    await this.processManager.spawnInteractive(this.command, args);
+    await this.processManager.spawnInteractive(this.command, args, {
+      env: this.buildCleanEnv(flags)
+    });
+  }
+  getPermissionMode() {
+    return process.env["RELAY_CLAUDE_PERMISSION_MODE"] === "default" ? "default" : "bypassPermissions";
   }
   async execute(flags) {
     if (!flags.prompt) {
       throw new Error("execute requires a prompt (-p flag)");
     }
-    const { args } = this.mapFlags(flags);
-    return this.processManager.execute(this.command, args);
+    const env = this.buildCleanEnv(flags);
+    const permissionMode = this.getPermissionMode();
+    try {
+      const options = {
+        env,
+        cwd: process.cwd(),
+        ...flags.model ? { model: flags.model } : {},
+        ...flags.maxTurns ? { maxTurns: flags.maxTurns } : {}
+      };
+      if (permissionMode === "bypassPermissions") {
+        options.permissionMode = "bypassPermissions";
+        options.allowDangerouslySkipPermissions = true;
+      }
+      const q = query({
+        prompt: flags.prompt,
+        options
+      });
+      let resultText = "";
+      let sessionId = "";
+      let isError = false;
+      let errorMessages = [];
+      for await (const message of q) {
+        if (message.type === "result") {
+          sessionId = message.session_id;
+          if (message.subtype === "success") {
+            resultText = message.result;
+          } else {
+            isError = true;
+            errorMessages = message.errors;
+          }
+        }
+      }
+      logger.debug(`Claude SDK session: ${sessionId}`);
+      return {
+        exitCode: isError ? 1 : 0,
+        stdout: resultText,
+        stderr: errorMessages.join("\n")
+      };
+    } catch (error) {
+      return {
+        exitCode: 1,
+        stdout: "",
+        stderr: error instanceof Error ? error.message : String(error)
+      };
+    }
   }
-  async resumeSession(sessionId, _flags) {
-    await this.processManager.spawnInteractive(this.command, [
-      "-r",
-      sessionId
-    ]);
+  async *executeStreaming(flags) {
+    if (!flags.prompt) {
+      throw new Error("executeStreaming requires a prompt (-p flag)");
+    }
+    const env = this.buildCleanEnv(flags);
+    const permissionMode = this.getPermissionMode();
+    try {
+      const options = {
+        env,
+        cwd: process.cwd(),
+        ...flags.model ? { model: flags.model } : {},
+        ...flags.maxTurns ? { maxTurns: flags.maxTurns } : {}
+      };
+      if (permissionMode === "bypassPermissions") {
+        options.permissionMode = "bypassPermissions";
+        options.allowDangerouslySkipPermissions = true;
+      }
+      const q = query({
+        prompt: flags.prompt,
+        options
+      });
+      for await (const message of q) {
+        if (message.type === "assistant") {
+          const betaMessage = message.message;
+          if (betaMessage?.content) {
+            for (const block of betaMessage.content) {
+              if (block.type === "text" && block.text) {
+                yield { type: "text", text: block.text };
+              }
+            }
+          }
+          if (betaMessage?.usage) {
+            yield {
+              type: "usage",
+              inputTokens: betaMessage.usage.input_tokens ?? 0,
+              outputTokens: betaMessage.usage.output_tokens ?? 0
+            };
+          }
+        } else if (message.type === "tool_progress") {
+          const toolName = message.tool_name ?? "unknown";
+          yield {
+            type: "status",
+            message: `Running ${toolName}...`
+          };
+        } else if (message.type === "result") {
+          if (message.subtype === "success") {
+            const resultText = message.result;
+            yield {
+              type: "done",
+              result: { exitCode: 0, stdout: resultText, stderr: "" }
+            };
+          } else {
+            const errors = message.errors;
+            yield {
+              type: "done",
+              result: {
+                exitCode: 1,
+                stdout: "",
+                stderr: errors.join("\n")
+              }
+            };
+          }
+        }
+      }
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : String(error);
+      yield { type: "error", message: errorMessage };
+      yield {
+        type: "done",
+        result: { exitCode: 1, stdout: "", stderr: errorMessage }
+      };
+    }
   }
-  async listNativeSessions() {
-    logger.debug(
-      "listNativeSessions: claude --resume is interactive, returning empty array"
+  async resumeSession(sessionId, flags) {
+    await this.processManager.spawnInteractive(
+      this.command,
+      ["-r", sessionId],
+      { env: this.buildCleanEnv(flags) }
     );
-    return [];
+  }
+  buildCleanEnv(flags) {
+    const env = {};
+    for (const [key, value] of Object.entries(process.env)) {
+      if (value !== void 0 && !CLAUDE_NESTING_ENV_VARS.includes(key)) {
+        env[key] = value;
+      }
+    }
+    if (flags.mcpContext) {
+      env.RELAY_TRACE_ID = flags.mcpContext.traceId;
+      env.RELAY_PARENT_SESSION_ID = flags.mcpContext.parentSessionId;
+      env.RELAY_DEPTH = String(flags.mcpContext.depth);
+    }
+    return env;
+  }
+  async listNativeSessions() {
+    try {
+      const sessions = await listSessions({ limit: 20 });
+      return sessions.map((s) => ({
+        nativeId: s.sessionId,
+        startedAt: new Date(s.lastModified),
+        lastMessage: s.summary
+      }));
+    } catch (error) {
+      logger.debug(
+        `listNativeSessions failed: ${error instanceof Error ? error.message : String(error)}`
+      );
+      return [];
+    }
   }
   async auth(action) {
     await this.processManager.spawnInteractive(this.command, ["auth", action]);
@@ -292,6 +450,7 @@ var ClaudeAdapter = class extends BaseAdapter {
 };
 
 // src/adapters/codex-adapter.ts
+import { Codex } from "@openai/codex-sdk";
 var CodexAdapter = class extends BaseAdapter {
   id = "codex";
   command = "codex";
@@ -321,15 +480,135 @@ var CodexAdapter = class extends BaseAdapter {
         `Codex CLI does not support --agent flag. Ignoring agent "${flags.agent}".`
       );
     }
-    const args = [];
-    if (flags.model) {
-      args.push("--model", flags.model);
+    try {
+      const codexOptions = {};
+      if (flags.mcpContext) {
+        codexOptions.env = {
+          ...process.env,
+          RELAY_TRACE_ID: flags.mcpContext.traceId,
+          RELAY_PARENT_SESSION_ID: flags.mcpContext.parentSessionId,
+          RELAY_DEPTH: String(flags.mcpContext.depth)
+        };
+      }
+      const codex = new Codex(codexOptions);
+      const thread = codex.startThread({
+        ...flags.model ? { model: flags.model } : {},
+        workingDirectory: process.cwd(),
+        approvalPolicy: "never"
+      });
+      const result = await thread.run(flags.prompt);
+      return {
+        exitCode: 0,
+        stdout: result.finalResponse,
+        stderr: ""
+      };
+    } catch (error) {
+      return {
+        exitCode: 1,
+        stdout: "",
+        stderr: error instanceof Error ? error.message : String(error)
+      };
     }
-    if (flags.outputFormat === "json") {
-      args.push("--json");
+  }
+  async *executeStreaming(flags) {
+    if (!flags.prompt) {
+      throw new Error("executeStreaming requires a prompt (-p flag)");
+    }
+    if (flags.agent) {
+      logger.warn(
+        `Codex CLI does not support --agent flag. Ignoring agent "${flags.agent}".`
+      );
+    }
+    try {
+      const codexOptions = {};
+      if (flags.mcpContext) {
+        codexOptions.env = {
+          ...process.env,
+          RELAY_TRACE_ID: flags.mcpContext.traceId,
+          RELAY_PARENT_SESSION_ID: flags.mcpContext.parentSessionId,
+          RELAY_DEPTH: String(flags.mcpContext.depth)
+        };
+      }
+      const codex = new Codex(codexOptions);
+      const thread = codex.startThread({
+        ...flags.model ? { model: flags.model } : {},
+        workingDirectory: process.cwd(),
+        approvalPolicy: "never"
+      });
+      const streamedTurn = await thread.runStreamed(flags.prompt);
+      const completedMessages = [];
+      for await (const event of streamedTurn.events) {
+        if (event.type === "item.started") {
+          const item = event.item;
+          if (item?.type === "agent_message" && item.text) {
+            yield { type: "text", text: item.text };
+          } else if (item?.type === "command_execution") {
+            yield {
+              type: "tool_start",
+              tool: item.command ?? "command",
+              id: item.id ?? ""
+            };
+          } else if (item?.type === "file_change") {
+            yield {
+              type: "tool_start",
+              tool: "file_change",
+              id: item.id ?? ""
+            };
+          }
+        } else if (event.type === "item.completed") {
+          const item = event.item;
+          if (item?.type === "agent_message" && item.text) {
+            completedMessages.push(item.text);
+            yield { type: "text", text: item.text };
+          } else if (item?.type === "command_execution") {
+            yield {
+              type: "tool_end",
+              tool: item.command ?? "command",
+              id: item.id ?? "",
+              result: item.aggregated_output
+            };
+          } else if (item?.type === "file_change") {
+            yield {
+              type: "tool_end",
+              tool: "file_change",
+              id: item.id ?? ""
+            };
+          }
+        } else if (event.type === "turn.completed") {
+          const usage = event.usage;
+          if (usage) {
+            yield {
+              type: "usage",
+              inputTokens: (usage.input_tokens ?? 0) + (usage.cached_input_tokens ?? 0),
+              outputTokens: usage.output_tokens ?? 0
+            };
+          }
+          const finalResponse = completedMessages.join("\n");
+          yield {
+            type: "done",
+            result: { exitCode: 0, stdout: finalResponse, stderr: "" }
+          };
+        } else if (event.type === "turn.failed") {
+          const errorMessage = event.error?.message ?? "Turn failed";
+          yield {
+            type: "done",
+            result: { exitCode: 1, stdout: "", stderr: errorMessage }
+          };
+        } else if (event.type === "error") {
+          yield {
+            type: "error",
+            message: event.message ?? "Unknown error"
+          };
+        }
+      }
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : String(error);
+      yield { type: "error", message: errorMessage };
+      yield {
+        type: "done",
+        result: { exitCode: 1, stdout: "", stderr: errorMessage }
+      };
     }
-    args.push("exec", flags.prompt);
-    return this.processManager.execute(this.command, args);
   }
   async resumeSession(sessionId, flags) {
     const args = [];
@@ -480,7 +759,7 @@ var GeminiAdapter = class extends BaseAdapter {
 };
 
 // src/core/session-manager.ts
-import { readFile, writeFile, readdir, mkdir } from "fs/promises";
+import { readFile, writeFile, readdir, mkdir, chmod } from "fs/promises";
 import { join } from "path";
 import { homedir } from "os";
 import { nanoid } from "nanoid";
@@ -504,7 +783,8 @@ function fromSessionData(data) {
     updatedAt: new Date(data.updatedAt)
   };
 }
-var SessionManager = class {
+var SessionManager = class _SessionManager {
+  static SESSION_ID_PATTERN = /^relay-[A-Za-z0-9_-]+$/;
   sessionsDir;
   constructor(sessionsDir) {
     this.sessionsDir = sessionsDir ?? getSessionsDir(getRelayHome());
@@ -514,6 +794,9 @@ var SessionManager = class {
     await mkdir(this.sessionsDir, { recursive: true });
   }
   sessionPath(relaySessionId) {
+    if (!_SessionManager.SESSION_ID_PATTERN.test(relaySessionId)) {
+      throw new Error(`Invalid session ID: ${relaySessionId}`);
+    }
     return join(this.sessionsDir, `${relaySessionId}.json`);
   }
   /** Create a new relay session. */
@@ -530,11 +813,13 @@ var SessionManager = class {
       updatedAt: now,
       status: "active"
     };
+    const sessionFilePath = this.sessionPath(session.relaySessionId);
     await writeFile(
-      this.sessionPath(session.relaySessionId),
+      sessionFilePath,
       JSON.stringify(toSessionData(session), null, 2),
       "utf-8"
     );
+    await chmod(sessionFilePath, 384);
     return session;
   }
   /** Update an existing session. */
@@ -548,16 +833,19 @@ var SessionManager = class {
       ...updates,
       updatedAt: /* @__PURE__ */ new Date()
     };
+    const updateFilePath = this.sessionPath(relaySessionId);
     await writeFile(
-      this.sessionPath(relaySessionId),
+      updateFilePath,
       JSON.stringify(toSessionData(updated), null, 2),
       "utf-8"
     );
+    await chmod(updateFilePath, 384);
   }
   /** Get a session by relay session ID. */
   async get(relaySessionId) {
+    const filePath = this.sessionPath(relaySessionId);
     try {
-      const raw = await readFile(this.sessionPath(relaySessionId), "utf-8");
+      const raw = await readFile(filePath, "utf-8");
       return fromSessionData(JSON.parse(raw));
     } catch {
       return null;
@@ -601,7 +889,7 @@ var SessionManager = class {
 };
 
 // src/core/config-manager.ts
-import { readFile as readFile2, writeFile as writeFile2, mkdir as mkdir2 } from "fs/promises";
+import { readFile as readFile2, writeFile as writeFile2, mkdir as mkdir2, chmod as chmod2 } from "fs/promises";
 import { join as join2 } from "path";
 
 // src/schemas/config.schema.ts
@@ -653,7 +941,8 @@ var relayConfigSchema = z.object({
   }).optional(),
   telemetry: z.object({
     enabled: z.boolean()
-  }).optional()
+  }).optional(),
+  claudePermissionMode: z.enum(["default", "bypassPermissions"]).optional()
 });
 
 // src/core/config-manager.ts
@@ -746,6 +1035,7 @@ var ConfigManager = class {
     const dir = filePath.substring(0, filePath.lastIndexOf("/"));
     await mkdir2(dir, { recursive: true });
     await writeFile2(filePath, JSON.stringify(existing, null, 2), "utf-8");
+    await chmod2(filePath, 384);
   }
   /**
    * Syncs MCP server config to all registered backend adapters.
@@ -899,18 +1189,54 @@ var DEFAULT_HOOK_OUTPUT = {
   message: "",
   metadata: {}
 };
-var HooksEngine = class {
+var HooksEngine = class _HooksEngine {
   constructor(eventBus2, processManager2) {
     this.eventBus = eventBus2;
     this.processManager = processManager2;
   }
+  static COMMAND_PATTERN = /^[a-zA-Z0-9_./-]+$/;
+  static ARG_PATTERN = /^[a-zA-Z0-9_.=:/-]+$/;
   definitions = [];
   registered = false;
+  validateCommand(command) {
+    if (!command || command.trim().length === 0) {
+      throw new Error("Hook command cannot be empty");
+    }
+    if (!_HooksEngine.COMMAND_PATTERN.test(command)) {
+      throw new Error(
+        `Hook command contains invalid characters: "${command}". Only alphanumeric characters, dots, underscores, hyphens, and slashes are allowed.`
+      );
+    }
+    if (command.includes("..")) {
+      throw new Error(
+        `Hook command contains path traversal: "${command}"`
+      );
+    }
+  }
+  validateArgs(args) {
+    for (const arg of args) {
+      if (!_HooksEngine.ARG_PATTERN.test(arg)) {
+        throw new Error(
+          `Hook argument contains invalid characters: "${arg}". Only alphanumeric characters, dots, underscores, equals, colons, hyphens, and slashes are allowed.`
+        );
+      }
+    }
+  }
   /** Load hook definitions from config and register listeners on EventBus */
   loadConfig(config) {
-    this.definitions = config.definitions.filter(
-      (def) => def.enabled !== false
-    );
+    this.definitions = config.definitions.filter((def) => {
+      if (def.enabled === false) return false;
+      try {
+        this.validateCommand(def.command);
+        this.validateArgs(def.args ?? []);
+        return true;
+      } catch (error) {
+        logger.warn(
+          `Skipping hook with invalid command: ${error instanceof Error ? error.message : String(error)}`
+        );
+        return false;
+      }
+    });
     if (!this.registered) {
       for (const event of this.getUniqueEvents()) {
         this.eventBus.on(event, async () => {
@@ -957,6 +1283,8 @@ var HooksEngine = class {
     return this.definitions.filter((def) => def.event === event).length;
   }
   async executeHook(def, input) {
+    this.validateCommand(def.command);
+    this.validateArgs(def.args ?? []);
     const timeoutMs = def.timeout ?? DEFAULT_TIMEOUT_MS;
     const stdinData = JSON.stringify(input);
     const startTime = Date.now();
@@ -1068,7 +1396,7 @@ var INSTALL_GUIDES = {
 };
 
 // src/commands/backend.ts
-function createBackendCommand(backendId, registry2, sessionManager2, hooksEngine2) {
+function createBackendCommand(backendId, registry2, sessionManager2, hooksEngine2, contextMonitor2) {
   return defineCommand({
     meta: {
       name: backendId,
@@ -1163,10 +1491,57 @@ function createBackendCommand(backendId, registry2, sessionManager2, hooksEngine
       try {
         if (flags.prompt) {
           logger.debug(`Executing prompt on ${backendId}`);
-          const result = await adapter.execute(flags);
-          if (result.stdout) process.stdout.write(result.stdout);
-          if (result.stderr) process.stderr.write(result.stderr);
-          process.exitCode = result.exitCode;
+          if (adapter.executeStreaming) {
+            for await (const event of adapter.executeStreaming(flags)) {
+              switch (event.type) {
+                case "text":
+                  process.stdout.write(event.text);
+                  break;
+                case "tool_start":
+                  if (flags.verbose) {
+                    process.stderr.write(`
+[${event.tool}] started
+`);
+                  }
+                  break;
+                case "tool_end":
+                  if (flags.verbose) {
+                    process.stderr.write(`[${event.tool}] completed
+`);
+                  }
+                  break;
+                case "status":
+                  if (flags.verbose) {
+                    process.stderr.write(`[status] ${event.message}
+`);
+                  }
+                  break;
+                case "error":
+                  process.stderr.write(event.message);
+                  break;
+                case "usage": {
+                  if (contextMonitor2 && relaySessionId) {
+                    const maxTokens = backendId === "gemini" ? 128e3 : 2e5;
+                    contextMonitor2.updateUsage(
+                      relaySessionId,
+                      backendId,
+                      event.inputTokens + event.outputTokens,
+                      maxTokens
+                    );
+                  }
+                  break;
+                }
+                case "done":
+                  process.exitCode = event.result.exitCode;
+                  break;
+              }
+            }
+          } else {
+            const result = await adapter.execute(flags);
+            if (result.stdout) process.stdout.write(result.stdout);
+            if (result.stderr) process.stderr.write(result.stderr);
+            process.exitCode = result.exitCode;
+          }
         } else if (flags.continue) {
           logger.debug(`Continuing latest session on ${backendId}`);
           if (sessionManager2) {
@@ -1246,13 +1621,66 @@ function createBackendCommand(backendId, registry2, sessionManager2, hooksEngine
 
 // src/commands/update.ts
 import { defineCommand as defineCommand2 } from "citty";
+
+// src/infrastructure/version-check.ts
+async function getLatestNpmVersion(packageName) {
+  try {
+    const response = await fetch(
+      `https://registry.npmjs.org/${packageName}/latest`,
+      {
+        headers: { Accept: "application/json" },
+        signal: AbortSignal.timeout(5e3)
+      }
+    );
+    if (!response.ok) {
+      logger.debug(
+        `npm registry returned ${response.status} for ${packageName}`
+      );
+      return null;
+    }
+    const data = await response.json();
+    return data.version ?? null;
+  } catch (error) {
+    logger.debug(
+      `Failed to check npm registry: ${error instanceof Error ? error.message : String(error)}`
+    );
+    return null;
+  }
+}
+function compareSemver(a, b) {
+  const partsA = a.replace(/^v/, "").split(".").map(Number);
+  const partsB = b.replace(/^v/, "").split(".").map(Number);
+  for (let i = 0; i < 3; i++) {
+    const diff = (partsA[i] ?? 0) - (partsB[i] ?? 0);
+    if (diff !== 0) return diff;
+  }
+  return 0;
+}
+
+// src/commands/update.ts
+var PACKAGE_NAME = "@rk0429/agentic-relay";
+var CURRENT_VERSION = "0.3.0";
 function createUpdateCommand(registry2) {
   return defineCommand2({
     meta: {
       name: "update",
-      description: "Update all installed backend CLI tools"
+      description: "Update relay and all installed backend CLI tools"
     },
     async run() {
+      logger.info("Checking for relay updates...");
+      const latestVersion = await getLatestNpmVersion(PACKAGE_NAME);
+      if (latestVersion) {
+        if (compareSemver(latestVersion, CURRENT_VERSION) > 0) {
+          logger.warn(
+            `A newer version of relay is available: ${latestVersion} (current: ${CURRENT_VERSION})`
+          );
+          logger.info(`  Run: npm install -g ${PACKAGE_NAME}@latest`);
+        } else {
+          logger.success(`relay is up to date (${CURRENT_VERSION})`);
+        }
+      } else {
+        logger.debug("Could not check for relay updates");
+      }
       const adapters = registry2.list();
       if (adapters.length === 0) {
         logger.warn("No backends registered");
@@ -1366,11 +1794,14 @@ import { defineCommand as defineCommand4 } from "citty";
 // src/mcp-server/server.ts
 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 { createServer } from "http";
+import { randomUUID } from "crypto";
 import { z as z5 } from "zod";
 
 // src/mcp-server/recursion-guard.ts
 import { createHash } from "crypto";
-var RecursionGuard = class {
+var RecursionGuard = class _RecursionGuard {
   constructor(config = {
     maxDepth: 5,
     maxCallsPerSession: 20,
@@ -1378,17 +1809,50 @@ var RecursionGuard = class {
   }) {
     this.config = config;
   }
+  static MAX_ENTRIES = 1e3;
   callCounts = /* @__PURE__ */ new Map();
   promptHashes = /* @__PURE__ */ new Map();
+  /** Remove entries older than timeoutSec and enforce size limits */
+  cleanup() {
+    const now = Date.now();
+    const ttlMs = this.config.timeoutSec * 1e3;
+    for (const [key, value] of this.callCounts) {
+      if (now - value.createdAt > ttlMs) {
+        this.callCounts.delete(key);
+      }
+    }
+    for (const [key, value] of this.promptHashes) {
+      if (now - value.createdAt > ttlMs) {
+        this.promptHashes.delete(key);
+      }
+    }
+    if (this.callCounts.size > _RecursionGuard.MAX_ENTRIES) {
+      const sorted = [...this.callCounts.entries()].sort(
+        (a, b) => a[1].createdAt - b[1].createdAt
+      );
+      for (let i = 0; i < sorted.length - _RecursionGuard.MAX_ENTRIES; i++) {
+        this.callCounts.delete(sorted[i][0]);
+      }
+    }
+    if (this.promptHashes.size > _RecursionGuard.MAX_ENTRIES) {
+      const sorted = [...this.promptHashes.entries()].sort(
+        (a, b) => a[1].createdAt - b[1].createdAt
+      );
+      for (let i = 0; i < sorted.length - _RecursionGuard.MAX_ENTRIES; i++) {
+        this.promptHashes.delete(sorted[i][0]);
+      }
+    }
+  }
   /** Check if a spawn is allowed */
   canSpawn(context) {
+    this.cleanup();
     if (context.depth >= this.config.maxDepth) {
       return {
         allowed: false,
         reason: `Max depth exceeded: ${context.depth} >= ${this.config.maxDepth}`
       };
     }
-    const currentCount = this.callCounts.get(context.traceId) ?? 0;
+    const currentCount = this.callCounts.get(context.traceId)?.count ?? 0;
     if (currentCount >= this.config.maxCallsPerSession) {
       return {
         allowed: false,
@@ -1405,17 +1869,25 @@ var RecursionGuard = class {
   }
   /** Record a spawn invocation */
   recordSpawn(context) {
-    const currentCount = this.callCounts.get(context.traceId) ?? 0;
-    this.callCounts.set(context.traceId, currentCount + 1);
+    this.cleanup();
+    const entry = this.callCounts.get(context.traceId);
+    if (entry) {
+      entry.count += 1;
+    } else {
+      this.callCounts.set(context.traceId, { count: 1, createdAt: Date.now() });
+    }
     const key = `${context.backend}:${context.promptHash}`;
-    const existing = this.promptHashes.get(context.traceId) ?? [];
-    existing.push(key);
-    this.promptHashes.set(context.traceId, existing);
+    const hashEntry = this.promptHashes.get(context.traceId);
+    if (hashEntry) {
+      hashEntry.hashes.push(key);
+    } else {
+      this.promptHashes.set(context.traceId, { hashes: [key], createdAt: Date.now() });
+    }
   }
   /** Detect if the same (backend + promptHash) combination has appeared 3+ times */
   detectLoop(traceId, backend, promptHash) {
     const key = `${backend}:${promptHash}`;
-    const hashes = this.promptHashes.get(traceId) ?? [];
+    const hashes = this.promptHashes.get(traceId)?.hashes ?? [];
     const count = hashes.filter((h) => h === key).length;
     return count >= 3;
   }
@@ -1425,7 +1897,7 @@ var RecursionGuard = class {
   }
   /** Get call count for a trace */
   getCallCount(traceId) {
-    return this.callCounts.get(traceId) ?? 0;
+    return this.callCounts.get(traceId)?.count ?? 0;
   }
   /** Utility: compute a prompt hash */
   static hashPrompt(prompt) {
@@ -1450,7 +1922,7 @@ function buildContextFromEnv() {
   const depth = Number(process.env["RELAY_DEPTH"] ?? "0");
   return { traceId, parentSessionId, depth };
 }
-async function executeSpawnAgent(input, registry2, sessionManager2, guard, hooksEngine2) {
+async function executeSpawnAgent(input, registry2, sessionManager2, guard, hooksEngine2, contextMonitor2) {
   const envContext = buildContextFromEnv();
   const promptHash = RecursionGuard.hashPrompt(input.prompt);
   const context = {
@@ -1518,6 +1990,18 @@ async function executeSpawnAgent(input, registry2, sessionManager2, guard, hooks
         traceId: envContext.traceId
       }
     });
+    if (contextMonitor2) {
+      const estimatedTokens = Math.ceil(
+        (result.stdout.length + result.stderr.length) / 4
+      );
+      const maxTokens = input.backend === "gemini" ? 128e3 : 2e5;
+      contextMonitor2.updateUsage(
+        session.relaySessionId,
+        input.backend,
+        estimatedTokens,
+        maxTokens
+      );
+    }
     guard.recordSpawn(context);
     const status = result.exitCode === 0 ? "completed" : "error";
     await sessionManager2.update(session.relaySessionId, { status });
@@ -1616,7 +2100,7 @@ var RelayMCPServer = class {
     this.guard = new RecursionGuard(guardConfig);
     this.server = new McpServer({
       name: "agentic-relay",
-      version: "0.1.0"
+      version: "0.3.0"
     });
     this.registerTools();
   }
@@ -1641,7 +2125,8 @@ var RelayMCPServer = class {
             this.registry,
             this.sessionManager,
             this.guard,
-            this.hooksEngine
+            this.hooksEngine,
+            this.contextMonitor
           );
           const isError = result.exitCode !== 0;
           const text = isError ? `Error (exit ${result.exitCode}): ${result.stderr || result.stdout}` : `Session: ${result.sessionId}
@@ -1721,11 +2206,47 @@ ${result.stdout}`;
       }
     );
   }
-  async start() {
-    logger.info("Starting agentic-relay MCP server (stdio transport)...");
-    const transport = new StdioServerTransport();
-    await this.server.connect(transport);
+  async start(options) {
+    const transportType = options?.transport ?? "stdio";
+    if (transportType === "stdio") {
+      logger.info("Starting agentic-relay MCP server (stdio transport)...");
+      const transport = new StdioServerTransport();
+      await this.server.connect(transport);
+      return;
+    }
+    const port = options?.port ?? 3100;
+    logger.info(
+      `Starting agentic-relay MCP server (HTTP transport on port ${port})...`
+    );
+    const httpTransport = new StreamableHTTPServerTransport({
+      sessionIdGenerator: () => randomUUID()
+    });
+    const httpServer = createServer(async (req, res) => {
+      const url = req.url ?? "";
+      if (url === "/mcp" || url.startsWith("/mcp?")) {
+        await httpTransport.handleRequest(req, res);
+      } else {
+        res.writeHead(404, { "Content-Type": "text/plain" });
+        res.end("Not found");
+      }
+    });
+    this._httpServer = httpServer;
+    await this.server.connect(httpTransport);
+    await new Promise((resolve) => {
+      httpServer.listen(port, () => {
+        logger.info(`MCP server listening on http://localhost:${port}/mcp`);
+        resolve();
+      });
+    });
+    await new Promise((resolve) => {
+      httpServer.on("close", resolve);
+    });
+  }
+  /** Exposed for testing and graceful shutdown */
+  get httpServer() {
+    return this._httpServer;
   }
+  _httpServer;
 };
 
 // src/commands/mcp.ts
@@ -1849,9 +2370,21 @@ function createMCPCommand(configManager2, registry2, sessionManager2, hooksEngin
       serve: defineCommand4({
         meta: {
           name: "serve",
-          description: "Start relay as an MCP server (stdio transport)"
+          description: "Start relay as an MCP server"
         },
-        async run() {
+        args: {
+          transport: {
+            type: "string",
+            description: "Transport type: stdio or http (default: stdio)",
+            default: "stdio"
+          },
+          port: {
+            type: "string",
+            description: "Port for HTTP transport (default: 3100)",
+            default: "3100"
+          }
+        },
+        async run({ args }) {
           if (!sessionManager2) {
             logger.error("SessionManager is required for MCP server mode");
             process.exitCode = 1;
@@ -1869,6 +2402,8 @@ function createMCPCommand(configManager2, registry2, sessionManager2, hooksEngin
             }
           } catch {
           }
+          const transport = args.transport === "http" ? "http" : "stdio";
+          const port = parseInt(String(args.port), 10) || 3100;
           const server = new RelayMCPServer(
             registry2,
             sessionManager2,
@@ -1876,7 +2411,7 @@ function createMCPCommand(configManager2, registry2, sessionManager2, hooksEngin
             hooksEngine2,
             contextMonitor2
           );
-          await server.start();
+          await server.start({ transport, port });
         }
       })
     },
@@ -2257,15 +2792,13 @@ var configManager = new ConfigManager(relayHome, projectRelayDir);
 var authManager = new AuthManager(registry);
 var eventBus = new EventBus();
 var hooksEngine = new HooksEngine(eventBus, processManager);
-var contextMonitor = new ContextMonitor(hooksEngine, {
-  enabled: false
-  // Will be enabled from config at runtime
-});
+var contextMonitor = new ContextMonitor(hooksEngine);
 void configManager.getConfig().then((config) => {
   if (config.hooks) {
     hooksEngine.loadConfig(config.hooks);
   }
   if (config.contextMonitor) {
+    contextMonitor = new ContextMonitor(hooksEngine, config.contextMonitor);
   }
 }).catch(() => {
 });
@@ -2276,9 +2809,9 @@ var main = defineCommand10({
     description: "Unified CLI proxy for Claude Code, Codex CLI, and Gemini CLI"
   },
   subCommands: {
-    claude: createBackendCommand("claude", registry, sessionManager, hooksEngine),
-    codex: createBackendCommand("codex", registry, sessionManager, hooksEngine),
-    gemini: createBackendCommand("gemini", registry, sessionManager, hooksEngine),
+    claude: createBackendCommand("claude", registry, sessionManager, hooksEngine, contextMonitor),
+    codex: createBackendCommand("codex", registry, sessionManager, hooksEngine, contextMonitor),
+    gemini: createBackendCommand("gemini", registry, sessionManager, hooksEngine, contextMonitor),
     update: createUpdateCommand(registry),
     config: createConfigCommand(configManager),
     mcp: createMCPCommand(configManager, registry, sessionManager, hooksEngine, contextMonitor),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rk0429/agentic-relay",
-  "version": "0.1.2",
+  "version": "0.3.0",
   "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",
@@ -38,6 +38,7 @@
     "build": "tsup",
     "dev": "tsup --watch",
     "test": "vitest run",
+    "test:coverage": "vitest run --coverage",
     "test:watch": "vitest",
     "lint": "tsc --noEmit",
     "prepublishOnly": "pnpm test && pnpm build"
@@ -46,7 +47,9 @@
     "node": ">=22"
   },
   "dependencies": {
+    "@anthropic-ai/claude-agent-sdk": "^0.2.59",
     "@modelcontextprotocol/sdk": "^1.27.1",
+    "@openai/codex-sdk": "^0.105.0",
     "citty": "^0.1.6",
     "consola": "^3.4.0",
     "execa": "^9.5.2",
@@ -55,6 +58,7 @@
   },
   "devDependencies": {
     "@types/node": "^25.3.0",
+    "@vitest/coverage-v8": "^3.2.4",
     "tsup": "^8.4.0",
     "typescript": "^5.7.3",
     "vitest": "^3.0.7"