relayax-cli 0.3.66 → 0.4.12

package/README.md

@@ -1,42 +1,174 @@
-# relay-cli
+# relay
 
-Agent Team Marketplace CLI - 에이전트 팀을 검색하고 설치하세요.
+**The package manager for AI agents.**
+
+Write once, run on any harness. One command install. Built-in usage analytics.
+
+```bash
+npx relayax-cli install @gstack/code-review
+```
+
+```
+ ╭──────────────────────────────────────────────╮
+ │                                              │
+ │   relay — AI agent distribution for humans   │
+ │   and machines.                              │
+ │                                              │
+ │   ✓ installed @gstack/code-review (v2.1.0)   │
+ │   3 skills, 1 agent ready                    │
+ │                                              │
+ ╰──────────────────────────────────────────────╯
+```
+
+---
+
+## Why
+
+AI agents are stuck in silos. You build an agent for Claude Code — it doesn't work on OpenClaw. You share it on GitHub — no one knows it exists. You have no idea if anyone actually uses it.
+
+**Relay fixes this.**
+
+| Problem | Relay |
+|---|---|
+| Agents locked to one harness | Cross-harness compatibility (Claude, OpenClaw, nanoclaw) |
+| No distribution channel | `relay install` — one command, done |
+| Zero feedback from users | Built-in analytics — see which skills get used |
+
+---
 
 ## Quick Start
 
 ```bash
-# 글로벌 설치 없이 바로 사용
-npx relay-cli install @author/team-name
+# Install an agent — no setup required
+npx relayax-cli install @author/agent-name
 
-# 또는 글로벌 설치
-npm install -g relayax-cli
-relay install @author/team-name
+# Or install globally
+npm i -g relayax-cli
+relay install @author/agent-name
 ```
 
+That's it. The agent is ready in your `.relay/agents/` directory, compatible with your harness.
+
+---
+
+## For Agent Builders
+
+```bash
+# Publish your agent to the registry
+relay publish
+
+# See who's using it
+relay status --analytics
+```
+
+Relay tracks skill-level usage out of the box. No extra setup. You'll know exactly which skills land and which don't — so you can ship better agents, faster.
+
+### Package Format
+
+```yaml
+# team.yaml
+name: code-review
+version: 2.1.0
+harness:
+  - claude
+  - openclaw
+  - nanoclaw
+agents:
+  - name: reviewer
+    type: passive
+skills:
+  - name: review-pr
+  - name: security-check
+  - name: style-lint
+```
+
+One spec. Every harness.
+
+---
+
 ## Commands
 
-| Command | Description |
-|---------|-------------|
-| `relay init` | 초기 설정 (설치 경로, API URL) |
-| `relay search <keyword>` | 팀 검색 |
-| `relay install <name>` | 팀 설치 |
-| `relay list` | 설치된 팀 목록 |
-| `relay uninstall <name>` | 팀 제거 |
+| Command | What it does |
+|---|---|
+| `relay install <name>` | Install an agent |
+| `relay search <keyword>` | Find agents in the registry |
+| `relay publish` | Publish your agent |
+| `relay list` | List installed agents |
+| `relay status` | Check environment + analytics |
+| `relay update` | Update agents to latest |
+| `relay uninstall <name>` | Remove an agent |
+| `relay diff <name>` | See what changed between versions |
 
-## Options
+All output is JSON by default (for AI agents). Add `--pretty` for human-readable format.
 
-- `--pretty` - 사람이 읽기 좋은 포맷으로 출력 (기본: JSON)
-- `--json` - JSON 출력 (기본값, 에이전트 친화적)
+---
 
-## For AI Agents
+## How It Works
+
+```
+                    relay install @team/agent
+                            │
+                 ╭──────────┴──────────╮
+                 │   Relay Registry    │
+                 │  (relay.ax cloud)   │
+                 ╰──────────┬──────────╯
+                            │
+                 ╭──────────┴──────────╮
+                 │  relay agent spec   │
+                 │  (universal format) │
+                 ╰──┬───────┬───────┬──╯
+                    │       │       │
+              ┌─────┴─┐ ┌──┴───┐ ┌─┴──────┐
+              │Claude │ │Open  │ │nano    │
+              │ Code  │ │Claw  │ │claw    │
+              └───────┘ └──────┘ └────────┘
+```
 
-relay CLI는 에이전트가 1차 사용자입니다. 모든 출력은 JSON 기본입니다.
+Relay resolves the right format for your harness automatically. Builders write one spec, users install with one command.
+
+---
+
+## AI-Native
+
+Relay is built for AI agents as first-class users. The CLI outputs structured JSON so agents can search, install, and manage other agents autonomously.
 
 ```bash
-# 에이전트가 팀 검색
-relay search "keyword" | jq '.results[].slug'
+# An agent searching for tools
+relay search "database migration" | jq '.results[].slug'
+
+# An agent installing what it needs
+relay install @tools/db-migrate
+# → {"status":"ok","agent":"db-migrate","skills":["migrate","rollback","seed"]}
+```
 
-# 에이전트가 팀 설치
-relay install @author/team-name
-# → {"status":"ok","team":"Team Name","commands":[...]}
+Relay also ships as an **MCP server**, so any MCP-compatible agent can use it directly:
+
+```bash
+relay mcp
 ```
+
+---
+
+## Open Core
+
+The CLI and agent spec are open source (MIT). Build agents, publish them, self-host your own registry — no vendor lock-in.
+
+[relay.ax](https://relayax.com) provides the hosted registry with:
+- Private agent hosting
+- Organization management & access control
+- Usage analytics dashboard
+- Enterprise SSO & audit logs
+
+---
+
+## Community
+
+- [25+ production agents](https://relayax.com) ready to install
+- [Builder docs](https://relayax.com/docs) for creating your own
+- [Discord](#) for help and discussion
+
+---
+
+<p align="center">
+  <sub>Built by <a href="https://relayax.com">RelayAX</a></sub>
+</p>

package/dist/commands/create.js

@@ -143,7 +143,14 @@ function registerCreate(program) {
                 });
             }
         }
-        // 3. .relay/relay.yaml 생성
+        // 3. recommended_scope 자동 추천
+        //    rules/ 존재 or 프레임워크 태그 → local, 그 외 → global
+        const frameworkTags = ['nextjs', 'react', 'vue', 'angular', 'svelte', 'nuxt', 'remix', 'astro', 'django', 'rails', 'laravel', 'spring', 'express', 'fastapi', 'flask'];
+        const hasRules = fs_1.default.existsSync(path_1.default.join(projectPath, '.relay', 'rules'))
+            || fs_1.default.existsSync(path_1.default.join(projectPath, 'rules'));
+        const hasFrameworkTag = tags.some((t) => frameworkTags.includes(t.toLowerCase()));
+        const recommendedScope = (hasRules || hasFrameworkTag) ? 'local' : 'global';
+        // 4. .relay/relay.yaml 생성
         fs_1.default.mkdirSync(relayDir, { recursive: true });
         const yamlData = {
             name,
@@ -151,6 +158,7 @@ function registerCreate(program) {
             description,
             version: '1.0.0',
             type: 'hybrid',
+            recommended_scope: recommendedScope,
             tags,
             visibility,
             contents: [],
@@ -187,6 +195,7 @@ function registerCreate(program) {
                 status: 'ok',
                 name,
                 slug: slug,
+                recommended_scope: recommendedScope,
                 relay_yaml: 'created',
                 directories: createdDirs,
                 local_commands: localResults,
@@ -194,8 +203,11 @@ function registerCreate(program) {
             }));
         }
         else {
+            const scopeLabel = recommendedScope === 'global' ? '\x1b[32m글로벌\x1b[0m' : '\x1b[33m로컬\x1b[0m';
+            const scopeReason = hasRules ? 'rules/ 감지' : hasFrameworkTag ? '프레임워크 태그 감지' : '범용 에이전트';
             console.log(`\n\x1b[32m✓ ${name} 에이전트 프로젝트 생성 완료\x1b[0m\n`);
             console.log(`  .relay/relay.yaml 생성됨`);
+            console.log(`  recommended_scope: ${scopeLabel} (${scopeReason})`);
             if (createdDirs.length > 0) {
                 console.log(`  디렉토리 생성: ${createdDirs.join(', ')}`);
             }

package/dist/commands/diff.js

@@ -1,9 +1,15 @@
 "use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.registerDiff = registerDiff;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const os_1 = __importDefault(require("os"));
 const api_js_1 = require("../lib/api.js");
 const slug_js_1 = require("../lib/slug.js");
-const storage_js_1 = require("../lib/storage.js");
+const git_operations_js_1 = require("../lib/git-operations.js");
 function registerDiff(program) {
     program
         .command('diff <slug> <v1> <v2>')
@@ -13,6 +19,7 @@ function registerDiff(program) {
         try {
             const resolved = await (0, slug_js_1.resolveSlug)(slugInput);
             const versions = await (0, api_js_1.fetchAgentVersions)(resolved.full);
+            const info = await (0, api_js_1.fetchAgentInfo)(resolved.full);
             const ver1 = versions.find((v) => v.version === v1);
             const ver2 = versions.find((v) => v.version === v2);
             if (!ver1 || !ver2) {
@@ -21,19 +28,36 @@ function registerDiff(program) {
             if (!json) {
                 console.log(`\n\x1b[1m${resolved.full}\x1b[0m v${v1} ↔ v${v2} 비교 중...\n`);
             }
-            // Download both versions to temp dirs
-            const tempDir1 = (0, storage_js_1.makeTempDir)();
-            const tempDir2 = (0, storage_js_1.makeTempDir)();
-            try {
-                // Get download URLs for both versions via registry API
-                // For now, we use the current version's package_url as fallback
-                // The registry API returns the latest version; for specific versions,
-                // we'd need a version-specific endpoint
-                const info = await (0, api_js_1.fetchAgentInfo)(resolved.full);
-                if (!info.package_url) {
-                    throw new Error('패키지 URL을 가져올 수 없습니다');
+            // Use git diff if git_url is available
+            if (info.git_url) {
+                (0, git_operations_js_1.checkGitInstalled)();
+                const tempDir = fs_1.default.mkdtempSync(path_1.default.join(os_1.default.tmpdir(), 'relay-diff-'));
+                try {
+                    (0, git_operations_js_1.gitClone)(info.git_url, tempDir);
+                    const diffOutput = (0, git_operations_js_1.gitDiff)(tempDir, `v${v1}`, `v${v2}`);
+                    if (json) {
+                        console.log(JSON.stringify({
+                            slug: resolved.full,
+                            v1: { version: v1, created_at: ver1.created_at, changelog: ver1.changelog },
+                            v2: { version: v2, created_at: ver2.created_at, changelog: ver2.changelog },
+                            diff: diffOutput,
+                        }));
+                    }
+                    else {
+                        if (diffOutput.trim()) {
+                            console.log(diffOutput);
+                        }
+                        else {
+                            console.log('  변경 사항이 없습니다.');
+                        }
+                    }
                 }
-                // Since version-specific download isn't available yet, show versions info
+                finally {
+                    fs_1.default.rmSync(tempDir, { recursive: true, force: true });
+                }
+            }
+            else {
+                // Fallback: show version info only (no git URL available)
                 if (json) {
                     console.log(JSON.stringify({
                         slug: resolved.full,
@@ -50,13 +74,9 @@ function registerDiff(program) {
                     if (ver2.changelog)
                         console.log(`    ${ver2.changelog}`);
                     console.log();
-                    console.log(`\x1b[33m  버전별 패키지 다운로드 비교는 추후 지원 예정입니다.\x1b[0m`);
+                    console.log(`\x1b[33m  git 기반 diff는 새로 배포된 에이전트에서만 지원됩니다.\x1b[0m`);
                 }
             }
-            finally {
-                (0, storage_js_1.removeTempDir)(tempDir1);
-                (0, storage_js_1.removeTempDir)(tempDir2);
-            }
         }
         catch (err) {
             const message = err instanceof Error ? err.message : String(err);

package/dist/commands/export.d.ts

@@ -0,0 +1,2 @@
+import { Command } from 'commander';
+export declare function registerExport(program: Command): void;

package/dist/commands/export.js

@@ -0,0 +1,106 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerExport = registerExport;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const js_yaml_1 = __importDefault(require("js-yaml"));
+const manifest_generator_js_1 = require("../lib/manifest-generator.js");
+const paths_js_1 = require("../lib/paths.js");
+function registerExport(program) {
+    program
+        .command('export <platform>')
+        .description('로컬에서 플랫폼 네이티브 매니페스트를 생성합니다')
+        .option('--out <dir>', '출력 디렉토리 (기본: .relay/export/<platform>/)')
+        .option('--project <dir>', '프로젝트 루트 경로')
+        .action(async (platform, opts) => {
+        const json = program.opts().json ?? false;
+        const projectPath = (0, paths_js_1.resolveProjectPath)(opts.project);
+        const relayDir = path_1.default.join(projectPath, '.relay');
+        const relayYamlPath = path_1.default.join(relayDir, 'relay.yaml');
+        // Check relay.yaml exists
+        if (!fs_1.default.existsSync(relayYamlPath)) {
+            const msg = 'relay.yaml not found';
+            if (json) {
+                console.error(JSON.stringify({ error: 'NOT_FOUND', message: msg }));
+            }
+            else {
+                console.error(`\x1b[31m${msg}\x1b[0m`);
+                console.error('  relay.yaml이 있는 에이전트 디렉토리에서 실행하세요.');
+            }
+            process.exit(1);
+        }
+        // Validate platform
+        const validPlatforms = [...manifest_generator_js_1.SUPPORTED_PLATFORMS, 'all'];
+        if (!validPlatforms.includes(platform)) {
+            const msg = `지원하지 않는 플랫폼: ${platform}`;
+            if (json) {
+                console.error(JSON.stringify({ error: 'INVALID_PLATFORM', message: msg, supported: manifest_generator_js_1.SUPPORTED_PLATFORMS }));
+            }
+            else {
+                console.error(`\x1b[31m${msg}\x1b[0m`);
+                console.error(`  지원 플랫폼: ${manifest_generator_js_1.SUPPORTED_PLATFORMS.join(', ')}, all`);
+            }
+            process.exit(1);
+        }
+        // Parse relay.yaml
+        const yamlContent = fs_1.default.readFileSync(relayYamlPath, 'utf-8');
+        const raw = js_yaml_1.default.load(yamlContent) ?? {};
+        const manifestYaml = {
+            name: String(raw.name ?? ''),
+            slug: String(raw.slug ?? ''),
+            description: String(raw.description ?? ''),
+            version: String(raw.version ?? '1.0.0'),
+            source: raw.source ? String(raw.source) : undefined,
+            org_slug: raw.org_slug ? String(raw.org_slug) : undefined,
+            platforms: platform === 'all' ? undefined : [platform],
+        };
+        // Generate manifests
+        const files = (0, manifest_generator_js_1.generateManifests)(manifestYaml, relayDir);
+        if (files.length === 0) {
+            if (json) {
+                console.log(JSON.stringify({ status: 'empty', message: '생성할 매니페스트가 없습니다.' }));
+            }
+            else {
+                console.log('생성할 매니페스트가 없습니다.');
+            }
+            return;
+        }
+        // Determine output directory
+        const outDir = opts.out
+            ? path_1.default.resolve(opts.out)
+            : path_1.default.join(relayDir, 'export', platform);
+        fs_1.default.mkdirSync(outDir, { recursive: true });
+        // Write files
+        const written = [];
+        for (const file of files) {
+            const filePath = path_1.default.join(outDir, file.relativePath);
+            fs_1.default.mkdirSync(path_1.default.dirname(filePath), { recursive: true });
+            fs_1.default.writeFileSync(filePath, file.content);
+            written.push(file.relativePath);
+        }
+        if (json) {
+            console.log(JSON.stringify({ status: 'ok', platform, output_dir: outDir, files: written }));
+        }
+        else {
+            console.log(`\n\x1b[32m✓ 매니페스트 생성 완료\x1b[0m  (${platform})`);
+            console.log(`  출력: \x1b[36m${outDir}\x1b[0m\n`);
+            for (const f of written) {
+                console.log(`  \x1b[90m•\x1b[0m ${f}`);
+            }
+            // Platform-specific usage hints
+            console.log('');
+            if (platform === 'claude-code' || platform === 'all') {
+                console.log('  \x1b[90mClaude Code:\x1b[0m /plugin marketplace add <marketplace.json URL>');
+            }
+            if (platform === 'codex' || platform === 'all') {
+                console.log('  \x1b[90mCodex:\x1b[0m .codex-plugin/plugin.json을 Codex에 등록하세요');
+            }
+            if (platform === 'antigravity' || platform === 'all') {
+                console.log('  \x1b[90mAntigravity:\x1b[0m .agent/skills/를 프로젝트에 복사하세요');
+            }
+        }
+    });
+}

package/dist/commands/init.d.ts

@@ -1,13 +1,9 @@
 import { Command } from 'commander';
-/**
- * 글로벌 User 커맨드를 감지된 모든 에이전트 CLI에 설치한다.
- * ~/{skillsDir}/commands/relay/ 에 설치.
- * 기존 파일 중 현재 커맨드 목록에 없는 것은 제거한다.
- */
 export declare function installGlobalUserCommands(): {
     installed: boolean;
     commands: string[];
     tools: string[];
+    removed: string[];
 };
 /**
  * 글로벌 User 커맨드가 이미 설치되어 있는지 확인한다.

package/dist/commands/init.js

@@ -36,10 +36,15 @@ function showWelcome() {
         '  에이전트 CLI에 relay 커맨드를 연결합니다.',
         '',
         '  \x1b[2mUser 커맨드 (글로벌)\x1b[0m',
-        '  /relay-install     에이전트 탐색 & 설치',
-        '  /relay-status      설치 현황 & Space',
+        '  /relay-explore     에이전트 탐색 & 추천',
+        '  /relay-create      에이전트 생성 & 배포',
+        '  /relay-status      설치 현황 & Organization',
         '  /relay-uninstall   에이전트 삭제',
         '',
+        '  \x1b[2mCLI 명령어\x1b[0m',
+        '  relay install      에이전트 설치 (CLI 한 줄 완결)',
+        '  relay publish      재배포 (--patch/--minor/--major)',
+        '',
     ];
     console.log(lines.join('\n'));
 }
@@ -65,20 +70,28 @@ async function selectToolsInteractively(detectedIds) {
  * ~/{skillsDir}/commands/relay/ 에 설치.
  * 기존 파일 중 현재 커맨드 목록에 없는 것은 제거한다.
  */
+/** 제거된 레거시 커맨드 → 대체 안내 매핑 */
+const LEGACY_COMMANDS = {
+    'relay-install': 'relay install (CLI) 또는 /relay-explore',
+    'relay-publish': 'relay publish --patch (CLI) 또는 /relay-create',
+};
 function installGlobalUserCommands() {
     const globalCLIs = (0, ai_tools_js_1.detectGlobalCLIs)();
     const currentIds = new Set(command_adapter_js_1.USER_COMMANDS.map((c) => c.id));
     const commands = [];
     const tools = [];
-    // 감지된 CLI가 없으면 설치하지 않음 (사용자가 --tools로 지정하거나 CLI를 먼저 설치해야 함)
+    const removed = [];
     const targetDirs = globalCLIs.map((t) => ({ name: t.name, dir: (0, command_adapter_js_1.getGlobalCommandDirForTool)(t.skillsDir), getPath: (id) => (0, command_adapter_js_1.getGlobalCommandPathForTool)(t.skillsDir, id) }));
     for (const target of targetDirs) {
         fs_1.default.mkdirSync(target.dir, { recursive: true });
-        // 기존 파일 중 현재 목록에 없는 것 제거
+        // 기존 파일 중 현재 목록에 없는 것 제거 + 레거시 안내
         for (const file of fs_1.default.readdirSync(target.dir)) {
             const id = file.replace(/\.md$/, '');
             if (!currentIds.has(id)) {
                 fs_1.default.unlinkSync(path_1.default.join(target.dir, file));
+                if (LEGACY_COMMANDS[id] && !removed.includes(id)) {
+                    removed.push(id);
+                }
             }
         }
         // 현재 커맨드 설치 (덮어쓰기)
@@ -87,11 +100,10 @@ function installGlobalUserCommands() {
         }
         tools.push(target.name);
     }
-    // commands 목록은 한 번만
     for (const cmd of command_adapter_js_1.USER_COMMANDS) {
         commands.push(cmd.id);
     }
-    return { installed: true, commands, tools };
+    return { installed: true, commands, tools, removed };
 }
 /**
  * 글로벌 User 커맨드가 이미 설치되어 있는지 확인한다.
@@ -149,10 +161,12 @@ function registerInit(program) {
         // ── 1. 글로벌 User 커맨드 설치 ──
         let globalStatus = 'already';
         let globalTools = [];
+        let removedCommands = [];
         {
             const result = installGlobalUserCommands();
             globalStatus = hasGlobalUserCommands() ? 'updated' : 'installed';
             globalTools = result.tools;
+            removedCommands = result.removed;
             // Register relay-core in installed.json
             const installed = (0, config_js_1.loadInstalled)();
             installed['relay-core'] = {
@@ -245,6 +259,14 @@ function registerInit(program) {
         }
         else {
             console.log(`\n\x1b[32m✓ relay 초기화 완료\x1b[0m\n`);
+            // 레거시 커맨드 마이그레이션 안내
+            if (removedCommands.length > 0) {
+                console.log(`  \x1b[33m⚠ 변경된 커맨드:\x1b[0m`);
+                for (const id of removedCommands) {
+                    console.log(`    \x1b[31m✗ /${id}\x1b[0m → ${LEGACY_COMMANDS[id]}`);
+                }
+                console.log();
+            }
             // 글로벌
             {
                 const toolNames = globalTools.length > 0 ? globalTools.join(', ') : '(감지된 CLI 없음)';

package/dist/commands/install.js

@@ -9,6 +9,7 @@ const os_1 = __importDefault(require("os"));
 const path_1 = __importDefault(require("path"));
 const api_js_1 = require("../lib/api.js");
 const storage_js_1 = require("../lib/storage.js");
+const git_operations_js_1 = require("../lib/git-operations.js");
 const config_js_1 = require("../lib/config.js");
 const slug_js_1 = require("../lib/slug.js");
 const preamble_js_1 = require("../lib/preamble.js");
@@ -212,11 +213,10 @@ function registerInstall(program) {
                 throw new Error('에이전트 정보를 가져오지 못했습니다.');
             // Re-bind as non-optional so TypeScript tracks the narrowing through nested scopes
             let resolvedAgent = agent;
-            // Scope 자동결정: --global/--local 플래그 > agent_type 기반
+            // Scope 자동결정: --global/--local 플래그 > recommended_scope > agent_type 기반
             const scope = _opts.global ? 'global'
                 : _opts.local ? 'local'
-                    : resolvedAgent.type === 'passive' ? 'local'
-                        : 'global';
+                    : resolvedAgent.recommended_scope ?? (resolvedAgent.type === 'passive' ? 'local' : 'global');
             const agentDir = scope === 'global'
                 ? path_1.default.join(os_1.default.homedir(), '.relay', 'agents', parsed.owner, parsed.name)
                 : path_1.default.join(projectPath, '.relay', 'agents', parsed.owner, parsed.name);
@@ -240,31 +240,39 @@ function registerInstall(program) {
                     process.exit(1);
                 }
             }
-            // 3. Download package (retry once if signed URL expired)
-            let tarPath;
-            try {
-                tarPath = await (0, storage_js_1.downloadPackage)(resolvedAgent.package_url, tempDir);
+            // 3. Download package: prefer git clone, fallback to tar.gz
+            const requestedVersion = versionMatch ? versionMatch[2] : undefined;
+            if (resolvedAgent.git_url) {
+                // Git clone path
+                (0, git_operations_js_1.checkGitInstalled)();
+                const gitUrl = (0, git_operations_js_1.buildGitUrl)(resolvedAgent.git_url, { code: _opts.code });
+                await (0, storage_js_1.clonePackage)(gitUrl, agentDir, requestedVersion);
             }
-            catch (dlErr) {
-                const dlMsg = dlErr instanceof Error ? dlErr.message : String(dlErr);
-                if (dlMsg.includes('403') || dlMsg.includes('expired')) {
-                    // Signed URL expired — re-fetch agent info for new URL and retry
-                    if (!json) {
-                        console.error('\x1b[33m⚙ 다운로드 URL 만료, 재시도 중...\x1b[0m');
-                    }
-                    resolvedAgent = await (0, api_js_1.fetchAgentInfo)(slug);
+            else {
+                // Legacy tar.gz path (retry once if signed URL expired)
+                let tarPath;
+                try {
                     tarPath = await (0, storage_js_1.downloadPackage)(resolvedAgent.package_url, tempDir);
                 }
-                else {
-                    throw dlErr;
+                catch (dlErr) {
+                    const dlMsg = dlErr instanceof Error ? dlErr.message : String(dlErr);
+                    if (dlMsg.includes('403') || dlMsg.includes('expired')) {
+                        if (!json) {
+                            console.error('\x1b[33m⚙ 다운로드 URL 만료, 재시도 중...\x1b[0m');
+                        }
+                        resolvedAgent = await (0, api_js_1.fetchAgentInfo)(slug);
+                        tarPath = await (0, storage_js_1.downloadPackage)(resolvedAgent.package_url, tempDir);
+                    }
+                    else {
+                        throw dlErr;
+                    }
                 }
+                if (fs_1.default.existsSync(agentDir)) {
+                    fs_1.default.rmSync(agentDir, { recursive: true, force: true });
+                }
+                fs_1.default.mkdirSync(agentDir, { recursive: true });
+                await (0, storage_js_1.extractPackage)(tarPath, agentDir);
             }
-            // 4. Extract to .relay/agents/<slug>/
-            if (fs_1.default.existsSync(agentDir)) {
-                fs_1.default.rmSync(agentDir, { recursive: true, force: true });
-            }
-            fs_1.default.mkdirSync(agentDir, { recursive: true });
-            await (0, storage_js_1.extractPackage)(tarPath, agentDir);
             // 4.5. Inject preamble (update check) into SKILL.md and commands
             (0, preamble_js_1.injectPreambleToAgent)(agentDir, slug);
             // 5. Deploy symlinks to detected AI tool directories