agent-relay 1.6.0 → 2.0.4

package/packages/mcp/dist/cloud.d.ts

@@ -0,0 +1,108 @@
+/**
+ * Cloud Integration for Agent Relay MCP Server
+ *
+ * Provides cloud workspace detection, remote daemon connection,
+ * and workspace-aware socket discovery for cloud deployments.
+ */
+export interface CloudWorkspace {
+    workspaceId: string;
+    cloudApiUrl: string;
+    workspaceToken?: string;
+    ownerUserId?: string;
+}
+export interface DiscoveryResult {
+    socketPath: string;
+    project: string;
+    source: 'env' | 'cloud' | 'cwd' | 'scan';
+    isCloud: boolean;
+    workspace?: CloudWorkspace;
+}
+export interface CloudConnectionOptions {
+    /** Override socket path (for testing) */
+    socketPath?: string;
+    /** Override workspace detection */
+    workspace?: Partial<CloudWorkspace>;
+}
+/**
+ * Detect if running in a cloud workspace environment.
+ *
+ * Cloud workspaces set these environment variables:
+ * - WORKSPACE_ID: The unique workspace identifier
+ * - CLOUD_API_URL: The cloud API endpoint
+ * - WORKSPACE_TOKEN: Bearer token for API auth (optional)
+ * - WORKSPACE_OWNER_USER_ID: The workspace owner's user ID (optional)
+ */
+export declare function detectCloudWorkspace(): CloudWorkspace | null;
+/**
+ * Check if we're running in a cloud workspace.
+ */
+export declare function isCloudWorkspace(): boolean;
+/**
+ * Get the workspace-namespaced socket path.
+ *
+ * In cloud workspaces, sockets are stored at:
+ * /tmp/relay/{WORKSPACE_ID}/sockets/daemon.sock
+ *
+ * This provides multi-tenant isolation on shared infrastructure.
+ */
+export declare function getCloudSocketPath(workspaceId: string): string;
+/**
+ * Get the workspace-namespaced outbox path.
+ *
+ * In cloud workspaces, outbox directories are at:
+ * /tmp/relay/{WORKSPACE_ID}/outbox/{agentName}/
+ */
+export declare function getCloudOutboxPath(workspaceId: string, agentName: string): string;
+/**
+ * Discover relay daemon socket with cloud-awareness.
+ *
+ * Priority order:
+ * 1. RELAY_SOCKET environment variable (explicit path)
+ * 2. Cloud workspace socket (if WORKSPACE_ID is set)
+ * 3. RELAY_PROJECT environment variable (project name → data dir)
+ * 4. Current working directory .relay/config.json
+ * 5. Scan data directory for active sockets
+ *
+ * @param options - Optional configuration overrides
+ * @returns Discovery result with socket path, project info, and cloud status
+ */
+export declare function discoverSocket(options?: CloudConnectionOptions): DiscoveryResult | null;
+/**
+ * Make an authenticated request to the cloud API.
+ *
+ * @param workspace - Cloud workspace configuration
+ * @param path - API path (e.g., '/api/status')
+ * @param options - Fetch options
+ * @returns Response from the API
+ */
+export declare function cloudApiRequest(workspace: CloudWorkspace, path: string, options?: RequestInit): Promise<Response>;
+/**
+ * Get the workspace status from the cloud API.
+ */
+export declare function getWorkspaceStatus(workspace: CloudWorkspace): Promise<{
+    status: string;
+    agents?: string[];
+} | null>;
+export interface CloudConnectionInfo {
+    socketPath: string;
+    project: string;
+    isCloud: boolean;
+    workspace?: CloudWorkspace;
+    daemonUrl?: string;
+}
+/**
+ * Get connection info for the relay daemon.
+ *
+ * This function determines the best way to connect to the daemon:
+ * - In cloud environments: Uses workspace-namespaced socket
+ * - In local environments: Uses standard socket discovery
+ *
+ * @param options - Optional configuration overrides
+ * @returns Connection info or null if daemon not found
+ */
+export declare function getConnectionInfo(options?: CloudConnectionOptions): CloudConnectionInfo | null;
+/**
+ * Environment variable summary for debugging.
+ */
+export declare function getCloudEnvironmentSummary(): Record<string, string | undefined>;
+//# sourceMappingURL=cloud.d.ts.map

package/packages/mcp/dist/cloud.js

@@ -0,0 +1,328 @@
+/**
+ * Cloud Integration for Agent Relay MCP Server
+ *
+ * Provides cloud workspace detection, remote daemon connection,
+ * and workspace-aware socket discovery for cloud deployments.
+ */
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+// ============================================================================
+// Cloud Workspace Detection
+// ============================================================================
+/**
+ * Detect if running in a cloud workspace environment.
+ *
+ * Cloud workspaces set these environment variables:
+ * - WORKSPACE_ID: The unique workspace identifier
+ * - CLOUD_API_URL: The cloud API endpoint
+ * - WORKSPACE_TOKEN: Bearer token for API auth (optional)
+ * - WORKSPACE_OWNER_USER_ID: The workspace owner's user ID (optional)
+ */
+export function detectCloudWorkspace() {
+    const workspaceId = process.env.WORKSPACE_ID;
+    const cloudApiUrl = process.env.CLOUD_API_URL;
+    if (!workspaceId || !cloudApiUrl) {
+        return null;
+    }
+    return {
+        workspaceId,
+        cloudApiUrl,
+        workspaceToken: process.env.WORKSPACE_TOKEN,
+        ownerUserId: process.env.WORKSPACE_OWNER_USER_ID,
+    };
+}
+/**
+ * Check if we're running in a cloud workspace.
+ */
+export function isCloudWorkspace() {
+    return detectCloudWorkspace() !== null;
+}
+// ============================================================================
+// Workspace-Aware Socket Discovery
+// ============================================================================
+/**
+ * Get the workspace-namespaced socket path.
+ *
+ * In cloud workspaces, sockets are stored at:
+ * /tmp/relay/{WORKSPACE_ID}/sockets/daemon.sock
+ *
+ * This provides multi-tenant isolation on shared infrastructure.
+ */
+export function getCloudSocketPath(workspaceId) {
+    return `/tmp/relay/${workspaceId}/sockets/daemon.sock`;
+}
+/**
+ * Get the workspace-namespaced outbox path.
+ *
+ * In cloud workspaces, outbox directories are at:
+ * /tmp/relay/{WORKSPACE_ID}/outbox/{agentName}/
+ */
+export function getCloudOutboxPath(workspaceId, agentName) {
+    return `/tmp/relay/${workspaceId}/outbox/${agentName}`;
+}
+/**
+ * Find project root by looking for common markers.
+ * Scans up from startDir until it finds a marker or hits the filesystem root.
+ */
+function findProjectRoot(startDir = process.cwd()) {
+    let current = startDir;
+    const root = current.split('/')[0] || '/';
+    const markers = ['.git', 'package.json', 'Cargo.toml', 'go.mod', 'pyproject.toml', '.agent-relay'];
+    while (current !== root && current !== '/') {
+        for (const marker of markers) {
+            if (existsSync(join(current, marker))) {
+                return current;
+            }
+        }
+        current = join(current, '..');
+    }
+    return null;
+}
+/**
+ * Get platform-specific data directory.
+ */
+function getDataDir() {
+    const platform = process.platform;
+    if (platform === 'darwin') {
+        return join(homedir(), 'Library', 'Application Support', 'agent-relay');
+    }
+    else if (platform === 'win32') {
+        return join(process.env.APPDATA || homedir(), 'agent-relay');
+    }
+    else {
+        return join(process.env.XDG_DATA_HOME || join(homedir(), '.local', 'share'), 'agent-relay');
+    }
+}
+/**
+ * Discover relay daemon socket with cloud-awareness.
+ *
+ * Priority order:
+ * 1. RELAY_SOCKET environment variable (explicit path)
+ * 2. Cloud workspace socket (if WORKSPACE_ID is set)
+ * 3. RELAY_PROJECT environment variable (project name → data dir)
+ * 4. Current working directory .relay/config.json
+ * 5. Scan data directory for active sockets
+ *
+ * @param options - Optional configuration overrides
+ * @returns Discovery result with socket path, project info, and cloud status
+ */
+export function discoverSocket(options = {}) {
+    // 0. Use override if provided
+    if (options.socketPath && existsSync(options.socketPath)) {
+        const workspace = options.workspace
+            ? {
+                workspaceId: options.workspace.workspaceId || 'override',
+                cloudApiUrl: options.workspace.cloudApiUrl || '',
+            }
+            : undefined;
+        return {
+            socketPath: options.socketPath,
+            project: workspace?.workspaceId || 'override',
+            source: 'env',
+            isCloud: !!workspace,
+            workspace,
+        };
+    }
+    // 1. Explicit socket path from environment
+    const socketEnv = process.env.RELAY_SOCKET;
+    if (socketEnv && existsSync(socketEnv)) {
+        const workspace = detectCloudWorkspace();
+        return {
+            socketPath: socketEnv,
+            project: process.env.RELAY_PROJECT || workspace?.workspaceId || 'unknown',
+            source: 'env',
+            isCloud: !!workspace,
+            workspace: workspace || undefined,
+        };
+    }
+    // 2. Cloud workspace socket (highest priority for cloud environments)
+    const workspace = detectCloudWorkspace();
+    if (workspace) {
+        const cloudSocket = getCloudSocketPath(workspace.workspaceId);
+        if (existsSync(cloudSocket)) {
+            return {
+                socketPath: cloudSocket,
+                project: workspace.workspaceId,
+                source: 'cloud',
+                isCloud: true,
+                workspace,
+            };
+        }
+    }
+    // 3. Project name → data dir lookup
+    const projectEnv = process.env.RELAY_PROJECT;
+    if (projectEnv) {
+        const dataDir = getDataDir();
+        const projectSocket = join(dataDir, 'projects', projectEnv, 'daemon.sock');
+        if (existsSync(projectSocket)) {
+            return {
+                socketPath: projectSocket,
+                project: projectEnv,
+                source: 'env',
+                isCloud: false,
+            };
+        }
+    }
+    // 4. Project-local socket (created by daemon in project's .agent-relay directory)
+    // This is the primary path for local development
+    // First try cwd, then scan up to find project root
+    const projectRoot = findProjectRoot(process.cwd());
+    const searchDirs = [process.cwd()];
+    if (projectRoot && projectRoot !== process.cwd()) {
+        searchDirs.push(projectRoot);
+    }
+    for (const dir of searchDirs) {
+        const projectLocalSocket = join(dir, '.agent-relay', 'relay.sock');
+        if (existsSync(projectLocalSocket)) {
+            // Read project ID from marker file if available
+            let projectId = 'local';
+            const markerPath = join(dir, '.agent-relay', '.project');
+            if (existsSync(markerPath)) {
+                try {
+                    const marker = JSON.parse(readFileSync(markerPath, 'utf-8'));
+                    projectId = marker.projectId || 'local';
+                }
+                catch {
+                    // Ignore marker read errors
+                }
+            }
+            return {
+                socketPath: projectLocalSocket,
+                project: projectId,
+                source: 'cwd',
+                isCloud: false,
+            };
+        }
+    }
+    // 4b. Legacy .relay/config.json support
+    const cwdConfig = join(process.cwd(), '.relay', 'config.json');
+    if (existsSync(cwdConfig)) {
+        try {
+            const config = JSON.parse(readFileSync(cwdConfig, 'utf-8'));
+            if (config.socketPath && existsSync(config.socketPath)) {
+                return {
+                    socketPath: config.socketPath,
+                    project: config.project || 'local',
+                    source: 'cwd',
+                    isCloud: false,
+                };
+            }
+        }
+        catch (err) {
+            // Invalid config (malformed JSON, permission error, etc.), continue to next method
+            if (process.env.DEBUG || process.env.RELAY_DEBUG) {
+                console.debug('[cloud] Failed to read cwd config:', cwdConfig, err);
+            }
+        }
+    }
+    // 5. Scan data directory for active sockets
+    const dataDir = getDataDir();
+    const projectsDir = join(dataDir, 'projects');
+    if (existsSync(projectsDir)) {
+        try {
+            const projects = readdirSync(projectsDir, { withFileTypes: true })
+                .filter((d) => d.isDirectory())
+                .map((d) => d.name);
+            for (const project of projects) {
+                const socketPath = join(projectsDir, project, 'daemon.sock');
+                if (existsSync(socketPath)) {
+                    return {
+                        socketPath,
+                        project,
+                        source: 'scan',
+                        isCloud: false,
+                    };
+                }
+            }
+        }
+        catch (err) {
+            // Directory read failed (permission error, etc.), return null
+            if (process.env.DEBUG || process.env.RELAY_DEBUG) {
+                console.debug('[cloud] Failed to scan projects directory:', projectsDir, err);
+            }
+        }
+    }
+    return null;
+}
+// ============================================================================
+// Cloud API Helpers
+// ============================================================================
+/**
+ * Make an authenticated request to the cloud API.
+ *
+ * @param workspace - Cloud workspace configuration
+ * @param path - API path (e.g., '/api/status')
+ * @param options - Fetch options
+ * @returns Response from the API
+ */
+export async function cloudApiRequest(workspace, path, options = {}) {
+    const url = `${workspace.cloudApiUrl}${path}`;
+    const headers = {
+        'Content-Type': 'application/json',
+        ...options.headers,
+    };
+    if (workspace.workspaceToken) {
+        headers['Authorization'] = `Bearer ${workspace.workspaceToken}`;
+    }
+    return fetch(url, {
+        ...options,
+        headers,
+    });
+}
+/**
+ * Get the workspace status from the cloud API.
+ */
+export async function getWorkspaceStatus(workspace) {
+    try {
+        const response = await cloudApiRequest(workspace, `/api/workspaces/${workspace.workspaceId}/status`);
+        if (!response.ok) {
+            return null;
+        }
+        return (await response.json());
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Get connection info for the relay daemon.
+ *
+ * This function determines the best way to connect to the daemon:
+ * - In cloud environments: Uses workspace-namespaced socket
+ * - In local environments: Uses standard socket discovery
+ *
+ * @param options - Optional configuration overrides
+ * @returns Connection info or null if daemon not found
+ */
+export function getConnectionInfo(options = {}) {
+    const discovery = discoverSocket(options);
+    if (!discovery) {
+        return null;
+    }
+    const info = {
+        socketPath: discovery.socketPath,
+        project: discovery.project,
+        isCloud: discovery.isCloud,
+        workspace: discovery.workspace,
+    };
+    // In cloud environments, we may also have a daemon URL for HTTP API access
+    if (discovery.workspace?.cloudApiUrl) {
+        info.daemonUrl = discovery.workspace.cloudApiUrl;
+    }
+    return info;
+}
+/**
+ * Environment variable summary for debugging.
+ */
+export function getCloudEnvironmentSummary() {
+    return {
+        WORKSPACE_ID: process.env.WORKSPACE_ID,
+        CLOUD_API_URL: process.env.CLOUD_API_URL,
+        WORKSPACE_TOKEN: process.env.WORKSPACE_TOKEN ? '[set]' : undefined,
+        WORKSPACE_OWNER_USER_ID: process.env.WORKSPACE_OWNER_USER_ID,
+        RELAY_SOCKET: process.env.RELAY_SOCKET,
+        RELAY_PROJECT: process.env.RELAY_PROJECT,
+    };
+}
+//# sourceMappingURL=cloud.js.map

package/packages/mcp/dist/errors.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Error Types for Agent Relay MCP Server
+ *
+ * Provides typed error classes for better error handling and messaging.
+ */
+export declare class RelayError extends Error {
+    constructor(message: string);
+}
+export declare class DaemonNotRunningError extends RelayError {
+    constructor(message?: string);
+}
+export declare class AgentNotFoundError extends RelayError {
+    constructor(agentName: string);
+}
+export declare class TimeoutError extends RelayError {
+    constructor(operation: string, timeoutMs: number);
+}
+export declare class ConnectionError extends RelayError {
+    constructor(message: string);
+}
+export declare class ChannelNotFoundError extends RelayError {
+    constructor(channel: string);
+}
+export declare class SpawnError extends RelayError {
+    constructor(workerName: string, reason: string);
+}
+//# sourceMappingURL=errors.d.ts.map

package/packages/mcp/dist/errors.js

@@ -0,0 +1,48 @@
+/**
+ * Error Types for Agent Relay MCP Server
+ *
+ * Provides typed error classes for better error handling and messaging.
+ */
+export class RelayError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'RelayError';
+    }
+}
+export class DaemonNotRunningError extends RelayError {
+    constructor(message) {
+        super(message || 'Relay daemon is not running. Start with: agent-relay up');
+        this.name = 'DaemonNotRunningError';
+    }
+}
+export class AgentNotFoundError extends RelayError {
+    constructor(agentName) {
+        super(`Agent not found: ${agentName}`);
+        this.name = 'AgentNotFoundError';
+    }
+}
+export class TimeoutError extends RelayError {
+    constructor(operation, timeoutMs) {
+        super(`Timeout after ${timeoutMs}ms: ${operation}`);
+        this.name = 'TimeoutError';
+    }
+}
+export class ConnectionError extends RelayError {
+    constructor(message) {
+        super(`Connection error: ${message}`);
+        this.name = 'ConnectionError';
+    }
+}
+export class ChannelNotFoundError extends RelayError {
+    constructor(channel) {
+        super(`Channel not found: ${channel}`);
+        this.name = 'ChannelNotFoundError';
+    }
+}
+export class SpawnError extends RelayError {
+    constructor(workerName, reason) {
+        super(`Failed to spawn worker "${workerName}": ${reason}`);
+        this.name = 'SpawnError';
+    }
+}
+//# sourceMappingURL=errors.js.map

package/packages/mcp/dist/index.d.ts

@@ -0,0 +1,10 @@
+export type { RelayClient } from './client.js';
+export { createRelayClient } from './client.js';
+export { createTools, send, inbox, who, type RelayTools, type ToolsConfig, type Message, type Agent, type Status, type SpawnResult, } from './simple.js';
+export { createMCPServer, runMCPServer, type MCPServerConfig } from './server.js';
+export { relaySendTool, relaySendSchema, handleRelaySend, type RelaySendInput, relayInboxTool, relayInboxSchema, handleRelayInbox, type RelayInboxInput, relayWhoTool, relayWhoSchema, handleRelayWho, type RelayWhoInput, relaySpawnTool, relaySpawnSchema, handleRelaySpawn, type RelaySpawnInput, relayReleaseTool, relayReleaseSchema, handleRelayRelease, type RelayReleaseInput, relayStatusTool, relayStatusSchema, handleRelayStatus, type RelayStatusInput, } from './tools/index.js';
+export { protocolPrompt, getProtocolPrompt, PROTOCOL_DOCUMENTATION } from './prompts/index.js';
+export { agentsResource, getAgentsResource, inboxResource, getInboxResource, projectResource, getProjectResource, } from './resources/index.js';
+export { RelayError, DaemonNotRunningError, AgentNotFoundError, TimeoutError, ConnectionError, ChannelNotFoundError, SpawnError, } from './errors.js';
+export { discoverSocket, detectCloudWorkspace, isCloudWorkspace, getCloudSocketPath, getConnectionInfo, type DiscoveryResult, type CloudWorkspace, type CloudConnectionInfo, } from './cloud.js';
+//# sourceMappingURL=index.d.ts.map

package/packages/mcp/dist/index.js

@@ -0,0 +1,16 @@
+export { createRelayClient } from './client.js';
+// Simple programmatic API (no MCP protocol overhead)
+export { createTools, send, inbox, who, } from './simple.js';
+// Server
+export { createMCPServer, runMCPServer } from './server.js';
+// Tools (for direct usage or custom server implementations)
+export { relaySendTool, relaySendSchema, handleRelaySend, relayInboxTool, relayInboxSchema, handleRelayInbox, relayWhoTool, relayWhoSchema, handleRelayWho, relaySpawnTool, relaySpawnSchema, handleRelaySpawn, relayReleaseTool, relayReleaseSchema, handleRelayRelease, relayStatusTool, relayStatusSchema, handleRelayStatus, } from './tools/index.js';
+// Prompts
+export { protocolPrompt, getProtocolPrompt, PROTOCOL_DOCUMENTATION } from './prompts/index.js';
+// Resources
+export { agentsResource, getAgentsResource, inboxResource, getInboxResource, projectResource, getProjectResource, } from './resources/index.js';
+// Errors
+export { RelayError, DaemonNotRunningError, AgentNotFoundError, TimeoutError, ConnectionError, ChannelNotFoundError, SpawnError, } from './errors.js';
+// Cloud/Discovery
+export { discoverSocket, detectCloudWorkspace, isCloudWorkspace, getCloudSocketPath, getConnectionInfo, } from './cloud.js';
+//# sourceMappingURL=index.js.map

package/packages/mcp/dist/install-cli.d.ts

@@ -0,0 +1,35 @@
+/**
+ * CLI wrapper for MCP installation
+ *
+ * Provides user-friendly interface for installing MCP server
+ * configuration in supported AI editors.
+ */
+export interface CliOptions {
+    /** Editor to configure (auto-detect if not specified) */
+    editor?: string;
+    /** Install globally instead of project-local */
+    global?: boolean;
+    /** Show what would be done without making changes */
+    dryRun?: boolean;
+    /** Uninstall instead of install */
+    uninstall?: boolean;
+    /** List supported editors */
+    list?: boolean;
+    /** Show installation status */
+    status?: boolean;
+    /** Quiet mode - minimal output */
+    quiet?: boolean;
+}
+/**
+ * Run the install command with CLI options
+ */
+export declare function runInstall(options?: CliOptions): void;
+/**
+ * Validate editor argument
+ */
+export declare function validateEditor(editor: string): boolean;
+/**
+ * Get list of valid editor keys for CLI help
+ */
+export declare function getValidEditors(): string[];
+//# sourceMappingURL=install-cli.d.ts.map