@rk0429/agentic-relay 2.0.10 → 3.0.0

package/README.md

@@ -1,329 +1,22 @@
 # 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/)
+`agentic-relay` is a TypeScript MCP server that launches Claude Code, Codex CLI,
+and Gemini CLI through a single `spawn_agents` tool.
 
-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.
+## Current scope
 
-## Why agentic-relay?
+- Phase 1 foundation from `docs/requirements.md`
+- `relay mcp serve` over stdio
+- Parallel `spawn_agents`
+- Backend routing, depth guard, response persistence, and session metadata
+- Automatic cross-backend handoff when `session_id` is resumed with a different backend
 
-Working with multiple AI coding CLIs means juggling different command syntaxes, configurations, and authentication flows. Nesting sub-agents across tools is not supported natively. And context window exhaustion catches you off guard.
-
-agentic-relay addresses three problems:
-
-| Problem | Solution |
-|---|---|
-| **Tool fragmentation** -- three CLIs with different flags, config formats, and auth mechanisms | Unified interface with backend adapters that normalize the differences |
-| **No nested sub-agents** -- parent agents cannot spawn grandchild agents through different backends | MCP server mode lets any MCP-capable client spawn agents across all three backends, with recursion guards |
-| **Context window surprise** -- sessions silently hit token limits | Hooks + ContextMonitor track usage and notify before the limit is reached |
-
-## Prerequisites
-
-- Node.js 22+
-- One or more backend tools installed: [Claude Code](https://docs.anthropic.com/en/docs/claude-code), [Codex CLI](https://github.com/openai/codex), or [Gemini CLI](https://github.com/google-gemini/gemini-cli)
-- macOS 13+ / Ubuntu 22.04+ / Debian 12+
-
-## Installation
-
-```bash
-# Install globally
-npm install -g @rk0429/agentic-relay
-
-# Initialize project-level config (optional)
-relay init
-
-# Verify installation
-relay doctor
-```
-
-### From Source
+## Usage
 
 ```bash
-git clone https://github.com/RK0429/agentic-relay.git
-cd agentic-relay
 pnpm install
 pnpm build
-pnpm link --global
-```
-
-## Quick Start
-
-```bash
-# Start an interactive session with Claude Code
-relay claude
-
-# One-shot prompt with Codex CLI
-relay codex -p "Refactor this function to use async/await"
-
-# Continue the latest Gemini session
-relay gemini -c
-
-# Check which backends are available
-relay doctor
-```
-
-## Usage
-
-### Backend Commands
-
-```bash
-relay claude|codex|gemini              # Interactive mode
-relay claude|codex|gemini -p "query"   # Non-interactive (one-shot)
-relay claude|codex|gemini -c           # Continue latest session
-relay claude|codex|gemini -r ID        # Resume session by ID
-relay claude|codex|gemini --agent NAME # Specify agent
-relay claude|codex|gemini --model NAME # Specify model
-```
-
-### Management Commands
-
-```bash
-relay config show               # Show merged config
-relay config get <key>          # Get config value
-relay config set <key> <value>  # Set config value
-relay auth <backend> login      # Authenticate a backend
-relay auth <backend> status     # Check auth status
-relay sessions                  # List/search sessions
-relay update                    # Update backend tools
-relay version                   # Show versions
-relay doctor                    # Run diagnostics
-relay init                      # Initialize .relay/ config
-```
-
-### MCP Commands
-
-```bash
-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 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
-
-agentic-relay uses a three-tier configuration system. Each tier overrides the one above it.
-
-| Tier | Path | Scope |
-|---|---|---|
-| Global | `~/.relay/config.json` | User-wide defaults |
-| Project | `.relay/config.json` | Shared across team (commit to VCS) |
-| Local | `.relay/config.local.json` | Personal overrides (gitignored) |
-
-Example configuration:
-
-```json
-{
-  "defaultBackend": "claude",
-  "mcpServers": {
-    "filesystem": {
-      "command": "npx",
-      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path"]
-    }
-  },
-  "hooks": {
-    "hooks": [
-      {
-        "event": "ContextThreshold",
-        "command": ["node", "scripts/save-state.js"],
-        "timeoutMs": 5000,
-        "onError": "warn"
-      }
-    ]
-  },
-  "contextMonitor": {
-    "enabled": true,
-    "thresholdPercent": 75,
-    "notifyMethod": "hook"
-  }
-}
+pnpm relay mcp serve
 ```
 
-### Environment Variables
-
-| Variable | Description | Default |
-|---|---|---|
-| `RELAY_HOME` | Home directory for relay | `~/.relay` |
-| `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` |
-| `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) | -- |
-
-### Security Considerations
-
-- **Claude adapter permission bypass**: By default, the Claude adapter runs with `bypassPermissions` mode to enable non-interactive sub-agent execution. This means spawned Claude Code agents can execute tools without user confirmation. To change this behavior, set the `RELAY_CLAUDE_PERMISSION_MODE` environment variable to `default`.
-
-## MCP Server Mode
-
-agentic-relay can act as an MCP (Model Context Protocol) server, allowing any MCP-capable client to spawn sub-agents across all three backends. This is how nested sub-agent orchestration works -- a parent agent calls relay via MCP, which spawns a child agent on any backend, and that child can call relay again to spawn a grandchild.
-
-### Setup
-
-Add relay as an MCP server in your client's configuration. For Claude Code:
-
-```json
-{
-  "mcpServers": {
-    "relay": {
-      "command": "relay",
-      "args": ["mcp", "serve"]
-    }
-  }
-}
-```
-
-### Exposed Tools
-
-| Tool | Description |
-|---|---|
-| `spawn_agent` | Spawn a sub-agent on a specified backend |
-| `list_sessions` | Retrieve session history |
-| `get_context_status` | Query context window usage |
-
-### Recursion Guard
-
-The MCP server includes a three-layer recursion guard to prevent runaway agent chains:
-
-1. **Depth limit** -- rejects calls that exceed the maximum nesting depth (default: 5)
-2. **Per-session call limit** -- caps the total number of spawns within a single session (default: 20)
-3. **Loop detection** -- identifies repeated calls with the same backend + prompt hash
-
-Context propagation between parent and child agents uses environment variables: `RELAY_TRACE_ID`, `RELAY_PARENT_SESSION_ID`, and `RELAY_DEPTH`.
-
-### Multi-layer Agent Call Flow
-
-```mermaid
-sequenceDiagram
-    participant User
-    participant Parent as Parent Agent<br>(Claude Code)
-    participant Relay as agentic-relay<br>(MCP Server)
-    participant Child as Child Agent<br>(Codex CLI)
-    participant Relay2 as agentic-relay<br>(MCP Server)
-    participant Grandchild as Grandchild Agent<br>(Gemini CLI)
-
-    User->>Parent: Task request
-    Parent->>Relay: spawn_agent(codex, prompt)
-    Note over Relay: RecursionGuard check<br>depth=1, calls=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: gemini -p "sub-prompt"<br>RELAY_DEPTH=2
-    Grandchild-->>Relay2: Result
-    Relay2-->>Child: Result
-    Child-->>Relay: Result
-    Relay-->>Parent: Result
-    Parent-->>User: Final answer
-```
-
-## Architecture
-
-agentic-relay is organized into six layers.
-
-```mermaid
-graph TD
-    A["CLI Layer<br><i>citty entry point</i>"] --> B["Command Handlers<br><i>backend, mcp, config, auth,<br>update, sessions, version, doctor, init</i>"]
-    B --> C["Core Layer<br><i>SessionManager, ConfigManager,<br>AuthManager, HooksEngine,<br>ContextMonitor, EventBus</i>"]
-    B --> D["MCP Server<br><i>RelayMCPServer,<br>spawn_agent, list_sessions,<br>get_context_status, RecursionGuard</i>"]
-    C --> E["Backend Adapters<br><i>BaseAdapter, ClaudeAdapter,<br>CodexAdapter, GeminiAdapter,<br>FlagMapper</i>"]
-    C --> F["Infrastructure<br><i>ProcessManager, Logger</i>"]
-    D --> E
-    D --> F
-```
-
-### Backend Adapters
-
-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.
-
-| Event | Trigger |
-|---|---|
-| `SessionStart` / `SessionEnd` | Session lifecycle |
-| `PreToolUse` / `PostToolUse` | Tool invocation |
-| `PreCompact` | Before context compaction |
-| `ContextThreshold` | Context usage exceeds threshold (relay-specific) |
-| `SubagentSpawn` / `SubagentComplete` | Sub-agent lifecycle (relay-specific) |
-
-### Context Monitor
-
-Monitors context window usage and fires `ContextThreshold` events when usage exceeds the configured threshold. Notification methods: `stderr` (direct output) or `hook` (triggers the Hooks Engine).
-
-## Project Structure
-
-```
-src/
-  bin/relay.ts                  # Entry point
-  commands/                     # Command handlers
-    backend.ts                  #   relay claude/codex/gemini
-    mcp.ts                      #   relay mcp (list/add/remove/sync/serve)
-    config.ts                   #   relay config
-    auth.ts                     #   relay auth
-    update.ts                   #   relay update
-    sessions.ts                 #   relay sessions
-    version.ts                  #   relay version
-    doctor.ts                   #   relay doctor
-    init.ts                     #   relay init
-  core/                         # Core modules
-    session-manager.ts
-    config-manager.ts
-    auth-manager.ts
-    hooks-engine.ts
-    context-monitor.ts
-    event-bus.ts
-  adapters/                     # Backend adapters
-    base-adapter.ts
-    claude-adapter.ts
-    codex-adapter.ts
-    gemini-adapter.ts
-    adapter-registry.ts
-    flag-mapper.ts
-    install-guides.ts
-  mcp-server/                   # MCP server mode
-    server.ts
-    recursion-guard.ts
-    tools/
-      spawn-agent.ts
-      list-sessions.ts
-      get-context-status.ts
-  infrastructure/               # Infrastructure
-    process-manager.ts
-    logger.ts
-  types/                        # Type definitions
-  schemas/                      # Zod validation schemas
-```
-
-## Tech Stack
-
-- **Runtime**: Node.js 22+
-- **Language**: TypeScript
-- **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 (interactive modes, Gemini CLI)
-- **Validation**: zod
-- **Logging**: consola
-- **Testing**: vitest (771 tests across 35 files)
-- **Coverage**: @vitest/coverage-v8
-
-## License
-
-Apache-2.0
+Responses are stored under `.relay/` in the current working directory.

package/dist/application/spawn-agents-service.d.ts

@@ -0,0 +1,20 @@
+import type { SpawnAgentResult, SpawnAgentsInput } from "../core/types.js";
+import { BackendRegistry } from "../infrastructure/backends/backend-registry.js";
+import { CliBackendExecutor } from "../infrastructure/backends/cli-backend-executor.js";
+import { RelayStore } from "../infrastructure/store/relay-store.js";
+export declare class SpawnAgentsService {
+    private readonly dependencies;
+    constructor(dependencies: {
+        backendRegistry: BackendRegistry;
+        backendExecutor: Pick<CliBackendExecutor, "execute">;
+        store: RelayStore;
+        cwd: string;
+        env?: NodeJS.ProcessEnv;
+    });
+    spawnAgents(input: SpawnAgentsInput, options?: {
+        signal?: AbortSignal;
+    }): Promise<SpawnAgentResult[]>;
+    private spawnSingleAgent;
+    private persistSuccess;
+    private persistFailure;
+}

package/dist/application/spawn-agents-service.js

@@ -0,0 +1,222 @@
+import { randomUUID } from "node:crypto";
+import { DepthLimitError } from "../core/errors.js";
+import { getCurrentDepth, resolveMaxDepth, validateDepth } from "../domain/depth.js";
+import { resolveBackend } from "../domain/routing.js";
+export class SpawnAgentsService {
+    dependencies;
+    constructor(dependencies) {
+        this.dependencies = dependencies;
+    }
+    async spawnAgents(input, options = {}) {
+        const env = this.dependencies.env ?? process.env;
+        const currentDepth = getCurrentDepth(env);
+        const maxDepth = resolveMaxDepth(input.max_depth, env);
+        validateDepth(currentDepth, maxDepth);
+        const installedBackends = await this.dependencies.backendRegistry.detectInstalled();
+        return Promise.all(input.agents.map((agent) => this.spawnSingleAgent({
+            agent,
+            currentDepth,
+            maxDepth,
+            installedBackends,
+            signal: options.signal,
+        })));
+    }
+    async spawnSingleAgent(options) {
+        const { agent, currentDepth, maxDepth, installedBackends, signal } = options;
+        const relaySessionId = randomUUID();
+        try {
+            const resumeMetadata = agent.session_id
+                ? await this.dependencies.store.readSessionMetadata(agent.session_id)
+                : null;
+            const resumeResponse = agent.session_id && resumeMetadata
+                ? await this.dependencies.store.readResponse(agent.session_id)
+                : null;
+            const routing = resolveBackend({
+                explicitBackend: agent.backend ?? resumeMetadata?.backend,
+                taskType: agent.task_type,
+                installedBackends,
+            });
+            const handoff = createHandoffInfo({
+                requestedSessionId: agent.session_id,
+                resumeMetadata,
+                resolvedBackend: routing.resolved,
+            });
+            const prompt = handoff
+                ? buildCrossBackendHandoffPrompt({
+                    sourceBackend: handoff.source_backend,
+                    sourceSessionId: handoff.source_session_id,
+                    responsePath: handoff.response_path,
+                    responseContent: resumeResponse,
+                    userPrompt: agent.prompt,
+                })
+                : agent.prompt;
+            await this.dependencies.store.appendLog(createLogEntry({
+                sessionId: relaySessionId,
+                taskId: agent.task_id,
+                backend: routing.resolved,
+                eventType: "agent_spawned",
+                status: "running",
+                details: {
+                    requested_backend: agent.backend,
+                    task_type: agent.task_type,
+                    handoff_mode: handoff?.mode,
+                    handoff_source_session_id: handoff?.source_session_id,
+                },
+            }));
+            if (routing.fellBack) {
+                await this.dependencies.store.appendLog(createLogEntry({
+                    sessionId: relaySessionId,
+                    taskId: agent.task_id,
+                    backend: routing.resolved,
+                    eventType: "routing_fallback",
+                    status: "success",
+                    details: {
+                        fallback_reason: routing.fallbackReason,
+                    },
+                }));
+            }
+            const executionResult = await this.dependencies.backendExecutor.execute({
+                relaySessionId,
+                backend: routing.resolved,
+                prompt,
+                systemPrompt: agent.system_prompt,
+                backendSessionId: handoff
+                    ? undefined
+                    : resumeMetadata?.backendSessionId ?? agent.session_id,
+                cwd: this.dependencies.cwd,
+                env: {
+                    ...process.env,
+                    ...(this.dependencies.env ?? {}),
+                    RELAY_CALL_DEPTH: String(currentDepth + 1),
+                    RELAY_MAX_DEPTH: String(maxDepth),
+                    RELAY_ALLOW_SPAWN_AGENTS: agent.task_type === "orchestration" ? "1" : "0",
+                },
+                signal,
+            });
+            return await this.persistSuccess({
+                relaySessionId,
+                agent,
+                backend: routing.resolved,
+                routing,
+                executionResult,
+                handoff,
+            });
+        }
+        catch (error) {
+            if (error instanceof DepthLimitError) {
+                throw error;
+            }
+            return await this.persistFailure({
+                relaySessionId,
+                agent,
+                error,
+            });
+        }
+    }
+    async persistSuccess(options) {
+        const summary = summarize(options.executionResult.output);
+        const responsePath = await this.dependencies.store.writeResponse(options.relaySessionId, options.executionResult.output);
+        const now = new Date().toISOString();
+        const metadata = {
+            relaySessionId: options.relaySessionId,
+            backend: options.backend,
+            backendSessionId: options.executionResult.backendSessionId,
+            cwd: this.dependencies.cwd,
+            createdAt: now,
+            updatedAt: now,
+            handoffFrom: options.handoff,
+        };
+        await this.dependencies.store.writeSessionMetadata(metadata);
+        await this.dependencies.store.appendLog(createLogEntry({
+            sessionId: options.relaySessionId,
+            taskId: options.agent.task_id,
+            backend: options.backend,
+            eventType: "agent_completed",
+            status: "success",
+        }));
+        return {
+            session_id: options.relaySessionId,
+            backend: options.backend,
+            summary,
+            full_response_path: responsePath,
+            status: "success",
+            routing: options.routing,
+            handoff: options.handoff,
+        };
+    }
+    async persistFailure(options) {
+        const message = options.error instanceof Error ? options.error.message : String(options.error);
+        const responsePath = await this.dependencies.store.writeResponse(options.relaySessionId, message);
+        const backend = options.agent.backend ?? "claude";
+        await this.dependencies.store.appendLog(createLogEntry({
+            sessionId: options.relaySessionId,
+            taskId: options.agent.task_id,
+            backend,
+            eventType: "agent_failed",
+            status: "error",
+            details: {
+                error: message,
+            },
+        }));
+        return {
+            session_id: options.relaySessionId,
+            backend,
+            summary: summarize(message),
+            full_response_path: responsePath,
+            status: "error",
+            routing: {
+                resolved: backend,
+                fellBack: false,
+            },
+        };
+    }
+}
+function summarize(content) {
+    return content.slice(0, 500);
+}
+function createLogEntry(options) {
+    return {
+        timestamp: new Date().toISOString(),
+        session_id: options.sessionId,
+        task_id: options.taskId,
+        backend: options.backend,
+        event_type: options.eventType,
+        status: options.status,
+        details: options.details,
+    };
+}
+function createHandoffInfo(options) {
+    const { requestedSessionId, resumeMetadata, resolvedBackend } = options;
+    if (!requestedSessionId || !resumeMetadata) {
+        return undefined;
+    }
+    if (resumeMetadata.backend === resolvedBackend) {
+        return undefined;
+    }
+    return {
+        mode: "cross_backend_handoff",
+        source_session_id: requestedSessionId,
+        source_backend: resumeMetadata.backend,
+        response_path: `${resumeMetadata.cwd}/.relay/responses/${requestedSessionId}.md`,
+    };
+}
+function buildCrossBackendHandoffPrompt(options) {
+    const excerpt = (options.responseContent ?? "").slice(0, 4000);
+    const excerptNote = options.responseContent && options.responseContent.length > 4000
+        ? "\nNote: the excerpt below is truncated. Read the full file if more context is needed."
+        : "";
+    return [
+        "Cross-backend handoff context:",
+        `- Source backend: ${options.sourceBackend}`,
+        `- Source relay session: ${options.sourceSessionId}`,
+        `- Full response path: ${options.responsePath}`,
+        excerptNote,
+        "",
+        "Previous backend final response excerpt:",
+        excerpt || "(response file could not be loaded)",
+        "",
+        "Continue the work using the following user prompt:",
+        options.userPrompt,
+    ].join("\n");
+}
+//# sourceMappingURL=spawn-agents-service.js.map

package/dist/application/spawn-agents-service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"spawn-agents-service.js","sourceRoot":"","sources":["../../src/application/spawn-agents-service.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAUzC,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AACpD,OAAO,EAAE,eAAe,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACrF,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAKtD,MAAM,OAAO,kBAAkB;IAEV;IADnB,YACmB,YAMhB;QANgB,iBAAY,GAAZ,YAAY,CAM5B;IACA,CAAC;IAEG,KAAK,CAAC,WAAW,CACtB,KAAuB,EACvB,UAAoC,EAAE;QAEtC,MAAM,GAAG,GAAG,IAAI,CAAC,YAAY,CAAC,GAAG,IAAI,OAAO,CAAC,GAAG,CAAC;QACjD,MAAM,YAAY,GAAG,eAAe,CAAC,GAAG,CAAC,CAAC;QAC1C,MAAM,QAAQ,GAAG,eAAe,CAAC,KAAK,CAAC,SAAS,EAAE,GAAG,CAAC,CAAC;QACvD,aAAa,CAAC,YAAY,EAAE,QAAQ,CAAC,CAAC;QAEtC,MAAM,iBAAiB,GAAG,MAAM,IAAI,CAAC,YAAY,CAAC,eAAe,CAAC,eAAe,EAAE,CAAC;QACpF,OAAO,OAAO,CAAC,GAAG,CAChB,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CACzB,IAAI,CAAC,gBAAgB,CAAC;YACpB,KAAK;YACL,YAAY;YACZ,QAAQ;YACR,iBAAiB;YACjB,MAAM,EAAE,OAAO,CAAC,MAAM;SACvB,CAAC,CACH,CACF,CAAC;IACJ,CAAC;IAEO,KAAK,CAAC,gBAAgB,CAAC,OAM9B;QACC,MAAM,EAAE,KAAK,EAAE,YAAY,EAAE,QAAQ,EAAE,iBAAiB,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC;QAC7E,MAAM,cAAc,GAAG,UAAU,EAAE,CAAC;QAEpC,IAAI,CAAC;YACH,MAAM,cAAc,GAAG,KAAK,CAAC,UAAU;gBACrC,CAAC,CAAC,MAAM,IAAI,CAAC,YAAY,CAAC,KAAK,CAAC,mBAAmB,CAAC,KAAK,CAAC,UAAU,CAAC;gBACrE,CAAC,CAAC,IAAI,CAAC;YACT,MAAM,cAAc,GAClB,KAAK,CAAC,UAAU,IAAI,cAAc;gBAChC,CAAC,CAAC,MAAM,IAAI,CAAC,YAAY,CAAC,KAAK,CAAC,YAAY,CAAC,KAAK,CAAC,UAAU,CAAC;gBAC9D,CAAC,CAAC,IAAI,CAAC;YAEX,MAAM,OAAO,GAAG,cAAc,CAAC;gBAC7B,eAAe,EAAE,KAAK,CAAC,OAAO,IAAI,cAAc,EAAE,OAAO;gBACzD,QAAQ,EAAE,KAAK,CAAC,SAAS;gBACzB,iBAAiB;aAClB,CAAC,CAAC;YACH,MAAM,OAAO,GAAG,iBAAiB,CAAC;gBAChC,kBAAkB,EAAE,KAAK,CAAC,UAAU;gBACpC,cAAc;gBACd,eAAe,EAAE,OAAO,CAAC,QAAQ;aAClC,CAAC,CAAC;YACH,MAAM,MAAM,GAAG,OAAO;gBACpB,CAAC,CAAC,8BAA8B,CAAC;oBAC7B,aAAa,EAAE,OAAO,CAAC,cAAc;oBACrC,eAAe,EAAE,OAAO,CAAC,iBAAiB;oBAC1C,YAAY,EAAE,OAAO,CAAC,aAAa;oBACnC,eAAe,EAAE,cAAc;oBAC/B,UAAU,EAAE,KAAK,CAAC,MAAM;iBACzB,CAAC;gBACJ,CAAC,CAAC,KAAK,CAAC,MAAM,CAAC;YAEjB,MAAM,IAAI,CAAC,YAAY,CAAC,KAAK,CAAC,SAAS,CACrC,cAAc,CAAC;gBACb,SAAS,EAAE,cAAc;gBACzB,MAAM,EAAE,KAAK,CAAC,OAAO;gBACrB,OAAO,EAAE,OAAO,CAAC,QAAQ;gBACzB,SAAS,EAAE,eAAe;gBAC1B,MAAM,EAAE,SAAS;gBACjB,OAAO,EAAE;oBACP,iBAAiB,EAAE,KAAK,CAAC,OAAO;oBAChC,SAAS,EAAE,KAAK,CAAC,SAAS;oBAC1B,YAAY,EAAE,OAAO,EAAE,IAAI;oBAC3B,yBAAyB,EAAE,OAAO,EAAE,iBAAiB;iBACtD;aACF,CAAC,CACH,CAAC;YAEF,IAAI,OAAO,CAAC,QAAQ,EAAE,CAAC;gBACrB,MAAM,IAAI,CAAC,YAAY,CAAC,KAAK,CAAC,SAAS,CACrC,cAAc,CAAC;oBACb,SAAS,EAAE,cAAc;oBACzB,MAAM,EAAE,KAAK,CAAC,OAAO;oBACrB,OAAO,EAAE,OAAO,CAAC,QAAQ;oBACzB,SAAS,EAAE,kBAAkB;oBAC7B,MAAM,EAAE,SAAS;oBACjB,OAAO,EAAE;wBACP,eAAe,EAAE,OAAO,CAAC,cAAc;qBACxC;iBACF,CAAC,CACH,CAAC;YACJ,CAAC;YAED,MAAM,eAAe,GAAG,MAAM,IAAI,CAAC,YAAY,CAAC,eAAe,CAAC,OAAO,CAAC;gBACtE,cAAc;gBACd,OAAO,EAAE,OAAO,CAAC,QAAQ;gBACzB,MAAM;gBACN,YAAY,EAAE,KAAK,CAAC,aAAa;gBACjC,gBAAgB,EAAE,OAAO;oBACvB,CAAC,CAAC,SAAS;oBACX,CAAC,CAAC,cAAc,EAAE,gBAAgB,IAAI,KAAK,CAAC,UAAU;gBACxD,GAAG,EAAE,IAAI,CAAC,YAAY,CAAC,GAAG;gBAC1B,GAAG,EAAE;oBACH,GAAG,OAAO,CAAC,GAAG;oBACd,GAAG,CAAC,IAAI,CAAC,YAAY,CAAC,GAAG,IAAI,EAAE,CAAC;oBAChC,gBAAgB,EAAE,MAAM,CAAC,YAAY,GAAG,CAAC,CAAC;oBAC1C,eAAe,EAAE,MAAM,CAAC,QAAQ,CAAC;oBACjC,wBAAwB,EACtB,KAAK,CAAC,SAAS,KAAK,eAAe,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG;iBAClD;gBACD,MAAM;aACP,CAAC,CAAC;YAEH,OAAO,MAAM,IAAI,CAAC,cAAc,CAAC;gBAC/B,cAAc;gBACd,KAAK;gBACL,OAAO,EAAE,OAAO,CAAC,QAAQ;gBACzB,OAAO;gBACP,eAAe;gBACf,OAAO;aACR,CAAC,CAAC;QACL,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,IAAI,KAAK,YAAY,eAAe,EAAE,CAAC;gBACrC,MAAM,KAAK,CAAC;YACd,CAAC;YACD,OAAO,MAAM,IAAI,CAAC,cAAc,CAAC;gBAC/B,cAAc;gBACd,KAAK;gBACL,KAAK;aACN,CAAC,CAAC;QACL,CAAC;IACH,CAAC;IAEO,KAAK,CAAC,cAAc,CAAC,OAO5B;QACC,MAAM,OAAO,GAAG,SAAS,CAAC,OAAO,CAAC,eAAe,CAAC,MAAM,CAAC,CAAC;QAC1D,MAAM,YAAY,GAAG,MAAM,IAAI,CAAC,YAAY,CAAC,KAAK,CAAC,aAAa,CAC9D,OAAO,CAAC,cAAc,EACtB,OAAO,CAAC,eAAe,CAAC,MAAM,CAC/B,CAAC;QAEF,MAAM,GAAG,GAAG,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;QACrC,MAAM,QAAQ,GAAyB;YACrC,cAAc,EAAE,OAAO,CAAC,cAAc;YACtC,OAAO,EAAE,OAAO,CAAC,OAAO;YACxB,gBAAgB,EAAE,OAAO,CAAC,eAAe,CAAC,gBAAgB;YAC1D,GAAG,EAAE,IAAI,CAAC,YAAY,CAAC,GAAG;YAC1B,SAAS,EAAE,GAAG;YACd,SAAS,EAAE,GAAG;YACd,WAAW,EAAE,OAAO,CAAC,OAAO;SAC7B,CAAC;QACF,MAAM,IAAI,CAAC,YAAY,CAAC,KAAK,CAAC,oBAAoB,CAAC,QAAQ,CAAC,CAAC;QAC7D,MAAM,IAAI,CAAC,YAAY,CAAC,KAAK,CAAC,SAAS,CACrC,cAAc,CAAC;YACb,SAAS,EAAE,OAAO,CAAC,cAAc;YACjC,MAAM,EAAE,OAAO,CAAC,KAAK,CAAC,OAAO;YAC7B,OAAO,EAAE,OAAO,CAAC,OAAO;YACxB,SAAS,EAAE,iBAAiB;YAC5B,MAAM,EAAE,SAAS;SAClB,CAAC,CACH,CAAC;QAEF,OAAO;YACL,UAAU,EAAE,OAAO,CAAC,cAAc;YAClC,OAAO,EAAE,OAAO,CAAC,OAAO;YACxB,OAAO;YACP,kBAAkB,EAAE,YAAY;YAChC,MAAM,EAAE,SAAS;YACjB,OAAO,EAAE,OAAO,CAAC,OAAO;YACxB,OAAO,EAAE,OAAO,CAAC,OAAO;SACzB,CAAC;IACJ,CAAC;IAEO,KAAK,CAAC,cAAc,CAAC,OAI5B;QACC,MAAM,OAAO,GACX,OAAO,CAAC,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,OAAO,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;QACjF,MAAM,YAAY,GAAG,MAAM,IAAI,CAAC,YAAY,CAAC,KAAK,CAAC,aAAa,CAC9D,OAAO,CAAC,cAAc,EACtB,OAAO,CACR,CAAC;QACF,MAAM,OAAO,GAAG,OAAO,CAAC,KAAK,CAAC,OAAO,IAAI,QAAQ,CAAC;QAElD,MAAM,IAAI,CAAC,YAAY,CAAC,KAAK,CAAC,SAAS,CACrC,cAAc,CAAC;YACb,SAAS,EAAE,OAAO,CAAC,cAAc;YACjC,MAAM,EAAE,OAAO,CAAC,KAAK,CAAC,OAAO;YAC7B,OAAO;YACP,SAAS,EAAE,cAAc;YACzB,MAAM,EAAE,OAAO;YACf,OAAO,EAAE;gBACP,KAAK,EAAE,OAAO;aACf;SACF,CAAC,CACH,CAAC;QAEF,OAAO;YACL,UAAU,EAAE,OAAO,CAAC,cAAc;YAClC,OAAO;YACP,OAAO,EAAE,SAAS,CAAC,OAAO,CAAC;YAC3B,kBAAkB,EAAE,YAAY;YAChC,MAAM,EAAE,OAAO;YACf,OAAO,EAAE;gBACP,QAAQ,EAAE,OAAO;gBACjB,QAAQ,EAAE,KAAK;aAChB;SACF,CAAC;IACJ,CAAC;CACF;AAED,SAAS,SAAS,CAAC,OAAe;IAChC,OAAO,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;AAC/B,CAAC;AAED,SAAS,cAAc,CAAC,OAOvB;IACC,OAAO;QACL,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;QACnC,UAAU,EAAE,OAAO,CAAC,SAAS;QAC7B,OAAO,EAAE,OAAO,CAAC,MAAM;QACvB,OAAO,EAAE,OAAO,CAAC,OAAO;QACxB,UAAU,EAAE,OAAO,CAAC,SAAS;QAC7B,MAAM,EAAE,OAAO,CAAC,MAAM;QACtB,OAAO,EAAE,OAAO,CAAC,OAAO;KACzB,CAAC;AACJ,CAAC;AAED,SAAS,iBAAiB,CAAC,OAI1B;IACC,MAAM,EAAE,kBAAkB,EAAE,cAAc,EAAE,eAAe,EAAE,GAAG,OAAO,CAAC;IACxE,IAAI,CAAC,kBAAkB,IAAI,CAAC,cAAc,EAAE,CAAC;QAC3C,OAAO,SAAS,CAAC;IACnB,CAAC;IAED,IAAI,cAAc,CAAC,OAAO,KAAK,eAAe,EAAE,CAAC;QAC/C,OAAO,SAAS,CAAC;IACnB,CAAC;IAED,OAAO;QACL,IAAI,EAAE,uBAAuB;QAC7B,iBAAiB,EAAE,kBAAkB;QACrC,cAAc,EAAE,cAAc,CAAC,OAAO;QACtC,aAAa,EAAE,GAAG,cAAc,CAAC,GAAG,qBAAqB,kBAAkB,KAAK;KACjF,CAAC;AACJ,CAAC;AAED,SAAS,8BAA8B,CAAC,OAMvC;IACC,MAAM,OAAO,GAAG,CAAC,OAAO,CAAC,eAAe,IAAI,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC;IAC/D,MAAM,WAAW,GACf,OAAO,CAAC,eAAe,IAAI,OAAO,CAAC,eAAe,CAAC,MAAM,GAAG,IAAI;QAC9D,CAAC,CAAC,uFAAuF;QACzF,CAAC,CAAC,EAAE,CAAC;IAET,OAAO;QACL,gCAAgC;QAChC,qBAAqB,OAAO,CAAC,aAAa,EAAE;QAC5C,2BAA2B,OAAO,CAAC,eAAe,EAAE;QACpD,yBAAyB,OAAO,CAAC,YAAY,EAAE;QAC/C,WAAW;QACX,EAAE;QACF,0CAA0C;QAC1C,OAAO,IAAI,qCAAqC;QAChD,EAAE;QACF,oDAAoD;QACpD,OAAO,CAAC,UAAU;KACnB,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACf,CAAC"}

package/dist/bin/relay.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/bin/relay.js

@@ -0,0 +1,47 @@
+#!/usr/bin/env node
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { SpawnAgentsService } from "../application/spawn-agents-service.js";
+import { BackendRegistry } from "../infrastructure/backends/backend-registry.js";
+import { CliBackendExecutor } from "../infrastructure/backends/cli-backend-executor.js";
+import { ChildProcessExecutor } from "../infrastructure/process/process-executor.js";
+import { RelayStore } from "../infrastructure/store/relay-store.js";
+import { createRelayMcpServer, serveRelayMcpServer, } from "../interfaces/mcp/relay-mcp-server.js";
+async function main() {
+    const args = process.argv.slice(2);
+    const cwd = process.cwd();
+    if (args[0] !== "mcp" || args[1] !== "serve") {
+        printHelp();
+        process.exitCode = 1;
+        return;
+    }
+    const backendRegistry = new BackendRegistry();
+    const installed = await backendRegistry.detectInstalled();
+    if (installed.length === 0) {
+        console.error("agentic-relay: no supported backend CLI is installed.");
+        process.exitCode = 1;
+        return;
+    }
+    const store = new RelayStore(path.join(cwd, ".relay"));
+    const service = new SpawnAgentsService({
+        backendRegistry,
+        backendExecutor: new CliBackendExecutor(backendRegistry, new ChildProcessExecutor()),
+        store,
+        cwd,
+        env: process.env,
+    });
+    const server = createRelayMcpServer({
+        service,
+        allowSpawnAgents: process.env.RELAY_ALLOW_SPAWN_AGENTS !== "0",
+    });
+    await serveRelayMcpServer(server);
+}
+function printHelp() {
+    const scriptName = path.basename(fileURLToPath(import.meta.url));
+    console.error(`Usage: ${scriptName} mcp serve`);
+}
+main().catch((error) => {
+    console.error(error instanceof Error ? error.message : "agentic-relay failed unexpectedly.");
+    process.exitCode = 1;
+});
+//# sourceMappingURL=relay.js.map

package/dist/bin/relay.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"relay.js","sourceRoot":"","sources":["../../src/bin/relay.ts"],"names":[],"mappings":";AACA,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACzC,OAAO,EAAE,kBAAkB,EAAE,MAAM,wCAAwC,CAAC;AAC5E,OAAO,EAAE,eAAe,EAAE,MAAM,gDAAgD,CAAC;AACjF,OAAO,EAAE,kBAAkB,EAAE,MAAM,oDAAoD,CAAC;AACxF,OAAO,EAAE,oBAAoB,EAAE,MAAM,+CAA+C,CAAC;AACrF,OAAO,EAAE,UAAU,EAAE,MAAM,wCAAwC,CAAC;AACpE,OAAO,EACL,oBAAoB,EACpB,mBAAmB,GACpB,MAAM,uCAAuC,CAAC;AAE/C,KAAK,UAAU,IAAI;IACjB,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;IACnC,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,EAAE,CAAC;IAE1B,IAAI,IAAI,CAAC,CAAC,CAAC,KAAK,KAAK,IAAI,IAAI,CAAC,CAAC,CAAC,KAAK,OAAO,EAAE,CAAC;QAC7C,SAAS,EAAE,CAAC;QACZ,OAAO,CAAC,QAAQ,GAAG,CAAC,CAAC;QACrB,OAAO;IACT,CAAC;IAED,MAAM,eAAe,GAAG,IAAI,eAAe,EAAE,CAAC;IAC9C,MAAM,SAAS,GAAG,MAAM,eAAe,CAAC,eAAe,EAAE,CAAC;IAC1D,IAAI,SAAS,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC3B,OAAO,CAAC,KAAK,CAAC,uDAAuD,CAAC,CAAC;QACvE,OAAO,CAAC,QAAQ,GAAG,CAAC,CAAC;QACrB,OAAO;IACT,CAAC;IAED,MAAM,KAAK,GAAG,IAAI,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,QAAQ,CAAC,CAAC,CAAC;IACvD,MAAM,OAAO,GAAG,IAAI,kBAAkB,CAAC;QACrC,eAAe;QACf,eAAe,EAAE,IAAI,kBAAkB,CACrC,eAAe,EACf,IAAI,oBAAoB,EAAE,CAC3B;QACD,KAAK;QACL,GAAG;QACH,GAAG,EAAE,OAAO,CAAC,GAAG;KACjB,CAAC,CAAC;IAEH,MAAM,MAAM,GAAG,oBAAoB,CAAC;QAClC,OAAO;QACP,gBAAgB,EAAE,OAAO,CAAC,GAAG,CAAC,wBAAwB,KAAK,GAAG;KAC/D,CAAC,CAAC;IAEH,MAAM,mBAAmB,CAAC,MAAM,CAAC,CAAC;AACpC,CAAC;AAED,SAAS,SAAS;IAChB,MAAM,UAAU,GAAG,IAAI,CAAC,QAAQ,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;IACjE,OAAO,CAAC,KAAK,CAAC,UAAU,UAAU,YAAY,CAAC,CAAC;AAClD,CAAC;AAED,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,KAAK,EAAE,EAAE;IACrB,OAAO,CAAC,KAAK,CACX,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,oCAAoC,CAC9E,CAAC;IACF,OAAO,CAAC,QAAQ,GAAG,CAAC,CAAC;AACvB,CAAC,CAAC,CAAC"}

package/dist/core/errors.d.ts

@@ -0,0 +1,14 @@
+export declare class RelayError extends Error {
+    readonly code: string;
+    readonly causeData?: unknown;
+    constructor(code: string, message: string, causeData?: unknown);
+}
+export declare class ValidationError extends RelayError {
+    constructor(message: string, causeData?: unknown);
+}
+export declare class DepthLimitError extends RelayError {
+    constructor(message: string);
+}
+export declare class BackendUnavailableError extends RelayError {
+    constructor(message: string, causeData?: unknown);
+}