agent-relay 1.6.0 → 2.0.4

package/packages/trajectory/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@agent-relay/trajectory",
+  "version": "2.0.4",
+  "description": "Trajectory integration utilities (trail/PDERO) for Relay",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "clean": "rm -rf dist",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "dependencies": {
+    "@agent-relay/config": "2.0.4"
+  },
+  "devDependencies": {
+    "@types/node": "^22.19.3",
+    "typescript": "^5.9.3",
+    "vitest": "^3.2.4"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/AgentWorkforce/relay.git",
+    "directory": "packages/trajectory"
+  }
+}

package/packages/user-directory/dist/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * @relay/user-directory
+ *
+ * User directory service for per-user credential storage on workspace volumes.
+ */
+export { UserDirectoryService, getDefaultDataDir, getUserDirectoryService, createUserDirectoryService, } from './user-directory.js';
+//# sourceMappingURL=index.d.ts.map

package/packages/user-directory/dist/index.js

@@ -0,0 +1,7 @@
+/**
+ * @relay/user-directory
+ *
+ * User directory service for per-user credential storage on workspace volumes.
+ */
+export { UserDirectoryService, getDefaultDataDir, getUserDirectoryService, createUserDirectoryService, } from './user-directory.js';
+//# sourceMappingURL=index.js.map

package/packages/user-directory/dist/user-directory.d.ts

@@ -0,0 +1,121 @@
+/**
+ * User Directory Service
+ *
+ * Manages per-user directories on workspace volumes for CLI credential storage.
+ * Each user gets their own home directory at /data/users/{userId}/ with
+ * provider-specific subdirectories for credentials.
+ *
+ * Structure:
+ * /data/
+ * └── users/
+ *     ├── {userId1}/
+ *     │   ├── .claude/
+ *     │   │   └── .credentials.json
+ *     │   ├── .codex/
+ *     │   │   └── credentials.json
+ *     │   └── .config/
+ *     │       └── gcloud/
+ *     │           └── application_default_credentials.json
+ *     └── {userId2}/
+ *         └── ...
+ */
+/**
+ * Service for managing per-user directories on workspace volumes.
+ * Enables multi-user credential storage without conflicts.
+ */
+export declare class UserDirectoryService {
+    private baseDir;
+    private usersDir;
+    /**
+     * Create a new UserDirectoryService.
+     * @param baseDir - Base data directory (e.g., /data)
+     */
+    constructor(baseDir: string);
+    /**
+     * Get the home directory path for a user.
+     * Creates the directory if it doesn't exist.
+     *
+     * @param userId - User ID (UUID or similar)
+     * @returns Absolute path to user's home directory
+     * @throws Error if userId is invalid
+     */
+    getUserHome(userId: string): string;
+    /**
+     * Ensure a provider's credential directory exists for a user.
+     *
+     * @param userId - User ID
+     * @param provider - Provider name (claude, codex, gemini, etc.)
+     * @returns Absolute path to provider directory
+     */
+    ensureProviderDir(userId: string, provider: string): string;
+    /**
+     * Initialize a complete user environment with all provider directories.
+     *
+     * @param userId - User ID
+     * @returns User's home directory path
+     */
+    initializeUserEnvironment(userId: string): string;
+    /**
+     * Get environment variables for spawning an agent with user-specific HOME.
+     *
+     * @param userId - User ID
+     * @returns Environment variables to merge with process.env
+     */
+    getUserEnvironment(userId: string): Record<string, string>;
+    /**
+     * List all user IDs that have directories.
+     *
+     * @returns Array of user IDs
+     */
+    listUsers(): string[];
+    /**
+     * Check if a user has an existing directory.
+     *
+     * @param userId - User ID
+     * @returns True if directory exists
+     */
+    hasUserDirectory(userId: string): boolean;
+    /**
+     * Get the path to a provider's credentials file for a user.
+     *
+     * @param userId - User ID
+     * @param provider - Provider name
+     * @returns Absolute path to credentials file
+     */
+    getProviderCredentialPath(userId: string, provider: string): string;
+    /**
+     * Write an API key to the appropriate credential file for a provider.
+     * Handles provider-specific formats (e.g., Gemini uses .env format).
+     *
+     * @param userId - User ID
+     * @param provider - Provider name (gemini, google, etc.)
+     * @param apiKey - The API key to write
+     * @returns Path to the written credential file
+     */
+    writeApiKeyCredential(userId: string, provider: string, apiKey: string): string;
+    /**
+     * Validate a user ID to prevent path traversal and other issues.
+     *
+     * @param userId - User ID to validate
+     * @throws Error if userId is invalid
+     */
+    private validateUserId;
+    /**
+     * Ensure a directory exists, creating it recursively if needed.
+     */
+    private ensureDirectory;
+}
+/**
+ * Get the default data directory for user directories.
+ * Uses AGENT_RELAY_DATA_DIR if set, otherwise /data (for Fly.io volumes).
+ */
+export declare function getDefaultDataDir(): string;
+/**
+ * Get the singleton UserDirectoryService instance.
+ */
+export declare function getUserDirectoryService(): UserDirectoryService;
+/**
+ * Create a new UserDirectoryService for testing or custom paths.
+ */
+export declare function createUserDirectoryService(baseDir: string): UserDirectoryService;
+//# sourceMappingURL=user-directory.d.ts.map

package/packages/user-directory/dist/user-directory.js

@@ -0,0 +1,267 @@
+/**
+ * User Directory Service
+ *
+ * Manages per-user directories on workspace volumes for CLI credential storage.
+ * Each user gets their own home directory at /data/users/{userId}/ with
+ * provider-specific subdirectories for credentials.
+ *
+ * Structure:
+ * /data/
+ * └── users/
+ *     ├── {userId1}/
+ *     │   ├── .claude/
+ *     │   │   └── .credentials.json
+ *     │   ├── .codex/
+ *     │   │   └── credentials.json
+ *     │   └── .config/
+ *     │       └── gcloud/
+ *     │           └── application_default_credentials.json
+ *     └── {userId2}/
+ *         └── ...
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { createLogger } from '@agent-relay/resiliency';
+const logger = createLogger('user-directory');
+const PROVIDER_CONFIGS = {
+    claude: {
+        dir: '.claude',
+        credentialsFile: '.credentials.json',
+    },
+    codex: {
+        dir: '.codex',
+        credentialsFile: 'credentials.json',
+    },
+    gemini: {
+        dir: '.config/gcloud',
+        credentialsFile: 'application_default_credentials.json',
+    },
+    opencode: {
+        dir: '.opencode',
+        credentialsFile: 'credentials.json',
+    },
+    droid: {
+        dir: '.factory',
+        credentialsFile: 'credentials.json',
+    },
+    cursor: {
+        dir: '.cursor',
+        credentialsFile: 'auth.json',
+    },
+};
+/**
+ * All supported providers for initialization
+ */
+const ALL_PROVIDERS = Object.keys(PROVIDER_CONFIGS);
+/**
+ * Service for managing per-user directories on workspace volumes.
+ * Enables multi-user credential storage without conflicts.
+ */
+export class UserDirectoryService {
+    baseDir;
+    usersDir;
+    /**
+     * Create a new UserDirectoryService.
+     * @param baseDir - Base data directory (e.g., /data)
+     */
+    constructor(baseDir) {
+        this.baseDir = baseDir;
+        this.usersDir = path.join(baseDir, 'users');
+        // Ensure users directory exists
+        this.ensureDirectory(this.usersDir);
+        logger.info(`UserDirectoryService initialized at ${this.usersDir}`);
+    }
+    /**
+     * Get the home directory path for a user.
+     * Creates the directory if it doesn't exist.
+     *
+     * @param userId - User ID (UUID or similar)
+     * @returns Absolute path to user's home directory
+     * @throws Error if userId is invalid
+     */
+    getUserHome(userId) {
+        this.validateUserId(userId);
+        const userHome = path.join(this.usersDir, userId);
+        this.ensureDirectory(userHome);
+        return userHome;
+    }
+    /**
+     * Ensure a provider's credential directory exists for a user.
+     *
+     * @param userId - User ID
+     * @param provider - Provider name (claude, codex, gemini, etc.)
+     * @returns Absolute path to provider directory
+     */
+    ensureProviderDir(userId, provider) {
+        this.validateUserId(userId);
+        const config = PROVIDER_CONFIGS[provider];
+        if (!config) {
+            // For unknown providers, use .{provider} directory
+            const userHome = this.getUserHome(userId);
+            const providerDir = path.join(userHome, `.${provider}`);
+            this.ensureDirectory(providerDir);
+            return providerDir;
+        }
+        const userHome = this.getUserHome(userId);
+        const providerDir = path.join(userHome, config.dir);
+        this.ensureDirectory(providerDir);
+        return providerDir;
+    }
+    /**
+     * Initialize a complete user environment with all provider directories.
+     *
+     * @param userId - User ID
+     * @returns User's home directory path
+     */
+    initializeUserEnvironment(userId) {
+        this.validateUserId(userId);
+        const userHome = this.getUserHome(userId);
+        // Create all provider directories
+        for (const provider of ALL_PROVIDERS) {
+            this.ensureProviderDir(userId, provider);
+        }
+        logger.info(`Initialized user environment for ${userId} at ${userHome}`);
+        return userHome;
+    }
+    /**
+     * Get environment variables for spawning an agent with user-specific HOME.
+     *
+     * @param userId - User ID
+     * @returns Environment variables to merge with process.env
+     */
+    getUserEnvironment(userId) {
+        const userHome = this.getUserHome(userId);
+        return {
+            HOME: userHome,
+            XDG_CONFIG_HOME: path.join(userHome, '.config'),
+            AGENT_RELAY_USER_ID: userId,
+        };
+    }
+    /**
+     * List all user IDs that have directories.
+     *
+     * @returns Array of user IDs
+     */
+    listUsers() {
+        try {
+            const entries = fs.readdirSync(this.usersDir, { withFileTypes: true });
+            return entries
+                .filter((entry) => entry.isDirectory())
+                .map((entry) => entry.name);
+        }
+        catch {
+            return [];
+        }
+    }
+    /**
+     * Check if a user has an existing directory.
+     *
+     * @param userId - User ID
+     * @returns True if directory exists
+     */
+    hasUserDirectory(userId) {
+        const userHome = path.join(this.usersDir, userId);
+        return fs.existsSync(userHome);
+    }
+    /**
+     * Get the path to a provider's credentials file for a user.
+     *
+     * @param userId - User ID
+     * @param provider - Provider name
+     * @returns Absolute path to credentials file
+     */
+    getProviderCredentialPath(userId, provider) {
+        const config = PROVIDER_CONFIGS[provider];
+        if (!config) {
+            const userHome = this.getUserHome(userId);
+            return path.join(userHome, `.${provider}`, 'credentials.json');
+        }
+        const providerDir = this.ensureProviderDir(userId, provider);
+        return path.join(providerDir, config.credentialsFile);
+    }
+    /**
+     * Write an API key to the appropriate credential file for a provider.
+     * Handles provider-specific formats (e.g., Gemini uses .env format).
+     *
+     * @param userId - User ID
+     * @param provider - Provider name (gemini, google, etc.)
+     * @param apiKey - The API key to write
+     * @returns Path to the written credential file
+     */
+    writeApiKeyCredential(userId, provider, apiKey) {
+        this.validateUserId(userId);
+        const userHome = this.getUserHome(userId);
+        // Gemini CLI reads from ~/.gemini/.env with GEMINI_API_KEY
+        if (provider === 'gemini' || provider === 'google') {
+            const geminiDir = path.join(userHome, '.gemini');
+            this.ensureDirectory(geminiDir);
+            const envPath = path.join(geminiDir, '.env');
+            fs.writeFileSync(envPath, `GEMINI_API_KEY="${apiKey}"\n`, { mode: 0o600 });
+            logger.info(`Wrote Gemini API key for user ${userId} to ${envPath}`);
+            return envPath;
+        }
+        // For other providers, use JSON format in the standard credential path
+        const credPath = this.getProviderCredentialPath(userId, provider);
+        const credDir = path.dirname(credPath);
+        this.ensureDirectory(credDir);
+        const credData = { apiKey, createdAt: new Date().toISOString() };
+        fs.writeFileSync(credPath, JSON.stringify(credData, null, 2), { mode: 0o600 });
+        logger.info(`Wrote ${provider} API key for user ${userId} to ${credPath}`);
+        return credPath;
+    }
+    /**
+     * Validate a user ID to prevent path traversal and other issues.
+     *
+     * @param userId - User ID to validate
+     * @throws Error if userId is invalid
+     */
+    validateUserId(userId) {
+        if (!userId || userId.trim() === '') {
+            throw new Error('User ID cannot be empty');
+        }
+        // Prevent path traversal
+        if (userId.includes('..') || userId.includes('/') || userId.includes('\\')) {
+            throw new Error('User ID contains invalid characters');
+        }
+        // Ensure resolved path is within users directory
+        const resolved = path.resolve(this.usersDir, userId);
+        if (!resolved.startsWith(this.usersDir)) {
+            throw new Error('User ID would escape users directory');
+        }
+    }
+    /**
+     * Ensure a directory exists, creating it recursively if needed.
+     */
+    ensureDirectory(dirPath) {
+        if (!fs.existsSync(dirPath)) {
+            fs.mkdirSync(dirPath, { recursive: true });
+        }
+    }
+}
+/**
+ * Get the default data directory for user directories.
+ * Uses AGENT_RELAY_DATA_DIR if set, otherwise /data (for Fly.io volumes).
+ */
+export function getDefaultDataDir() {
+    return process.env.AGENT_RELAY_DATA_DIR || '/data';
+}
+/**
+ * Singleton instance for the workspace.
+ */
+let _instance = null;
+/**
+ * Get the singleton UserDirectoryService instance.
+ */
+export function getUserDirectoryService() {
+    if (!_instance) {
+        _instance = new UserDirectoryService(getDefaultDataDir());
+    }
+    return _instance;
+}
+/**
+ * Create a new UserDirectoryService for testing or custom paths.
+ */
+export function createUserDirectoryService(baseDir) {
+    return new UserDirectoryService(baseDir);
+}
+//# sourceMappingURL=user-directory.js.map

package/packages/user-directory/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@agent-relay/user-directory",
+  "version": "2.0.4",
+  "description": "User directory service for agent-relay (per-user credential storage)",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "clean": "rm -rf dist",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "dependencies": {
+    "@agent-relay/resiliency": "2.0.4"
+  },
+  "devDependencies": {
+    "@types/node": "^22.19.3",
+    "typescript": "^5.9.3",
+    "vitest": "^3.2.4"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/AgentWorkforce/relay.git",
+    "directory": "packages/user-directory"
+  }
+}

package/packages/utils/dist/command-resolver.js

@@ -0,0 +1,80 @@
+/**
+ * Command Path Resolver
+ *
+ * Resolves full paths for CLI commands to avoid posix_spawnp failures
+ * when PATH isn't properly inherited in spawned processes.
+ */
+import { execSync } from 'node:child_process';
+import fs from 'node:fs';
+/**
+ * Resolve the full path of a command using 'which' and resolve any symlinks
+ * Returns the full path if found, or the original command if not found
+ * (letting the spawn fail with a clearer error)
+ */
+export function resolveCommand(command) {
+    // If already an absolute path, just resolve symlinks
+    if (command.startsWith('/')) {
+        return resolveSymlinks(command);
+    }
+    try {
+        const output = execSync(`which ${command}`, {
+            encoding: 'utf-8',
+            stdio: ['pipe', 'pipe', 'pipe'],
+            // Ensure we have a reasonable PATH
+            env: {
+                ...process.env,
+                PATH: process.env.PATH || '/usr/local/bin:/usr/bin:/bin:/opt/homebrew/bin',
+            },
+        });
+        const resolvedPath = output.trim();
+        if (resolvedPath) {
+            // Resolve any symlinks to get the actual binary path
+            // This fixes posix_spawnp issues with symlinked binaries
+            return resolveSymlinks(resolvedPath);
+        }
+    }
+    catch (err) {
+        // Command not found in PATH - log for debugging
+        console.warn(`[command-resolver] 'which ${command}' failed:`, err.message?.split('\n')[0] || 'unknown error');
+    }
+    // Return original command - spawn will fail with a clearer error
+    return command;
+}
+/**
+ * Resolve symlinks to get the actual file path
+ * Uses fs.realpathSync which handles all symlink levels
+ */
+function resolveSymlinks(filePath) {
+    try {
+        const resolved = fs.realpathSync(filePath);
+        // Debug log only - symlink resolution is noisy
+        if (resolved !== filePath && process.env.DEBUG_SPAWN === '1') {
+            console.log(`[command-resolver] Resolved symlink: ${filePath} -> ${resolved}`);
+        }
+        return resolved;
+    }
+    catch (err) {
+        // If realpath fails, return original (spawn will give clearer error)
+        // Only warn in debug mode - this is common and not actionable
+        if (process.env.DEBUG_SPAWN === '1') {
+            console.warn(`[command-resolver] realpath failed for ${filePath}:`, err.message);
+        }
+        return filePath;
+    }
+}
+/**
+ * Check if a command exists in PATH
+ */
+export function commandExists(command) {
+    try {
+        execSync(`which ${command}`, {
+            encoding: 'utf-8',
+            stdio: ['pipe', 'pipe', 'pipe'],
+        });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+//# sourceMappingURL=command-resolver.js.map

package/packages/utils/dist/error-tracking.d.ts

@@ -0,0 +1,103 @@
+/**
+ * Error Tracking Utilities
+ *
+ * Provides traceable error IDs that users can report to support.
+ * Support can then search logs for the error ID to find full context.
+ *
+ * Error ID format: ERR-{timestamp}-{random}
+ * Example: ERR-1706012345-a7f3
+ *
+ * Usage:
+ *   const error = createTraceableError('Failed to spawn agent', { agentName, cli });
+ *   console.error(error.logMessage); // Full details for logs
+ *   return { error: error.userMessage }; // Safe message with ID for user
+ */
+export interface TraceableError {
+    /** Unique error ID for support lookup (e.g., ERR-1706012345-a7f3) */
+    errorId: string;
+    /** User-facing message with error ID (safe to display) */
+    userMessage: string;
+    /** Full log message with all context (for server logs) */
+    logMessage: string;
+    /** ISO timestamp when error occurred */
+    timestamp: string;
+    /** Original error message */
+    message: string;
+    /** Additional context data */
+    context: Record<string, unknown>;
+}
+/**
+ * Generate a unique error ID.
+ * Format: ERR-{unix_timestamp}-{4_random_hex_chars}
+ */
+export declare function generateErrorId(): string;
+/**
+ * Create a traceable error with ID for support lookup.
+ *
+ * @param message - Human-readable error description
+ * @param context - Additional context (agentName, workspaceId, etc.)
+ * @param originalError - Original error object if wrapping
+ * @returns TraceableError with ID, user message, and log message
+ *
+ * @example
+ * ```typescript
+ * const error = createTraceableError('Failed to spawn agent', {
+ *   agentName: 'Worker1',
+ *   cli: 'claude',
+ *   reason: 'timeout'
+ * });
+ *
+ * // Log full details for support
+ * console.error(error.logMessage);
+ * // => [ERR-1706012345-a7f3] Failed to spawn agent | agentName=Worker1 cli=claude reason=timeout
+ *
+ * // Return safe message to user
+ * res.status(500).json({ error: error.userMessage });
+ * // => "Failed to spawn agent (Error ID: ERR-1706012345-a7f3 - share this with support)"
+ * ```
+ */
+export declare function createTraceableError(message: string, context?: Record<string, unknown>, originalError?: Error): TraceableError;
+/**
+ * Log a traceable error and return user-safe response.
+ * Convenience wrapper that logs and returns in one call.
+ *
+ * @example
+ * ```typescript
+ * const { userMessage, errorId } = logAndTraceError(
+ *   'Workspace creation failed',
+ *   { workspaceId, userId },
+ *   err
+ * );
+ * res.status(500).json({ error: userMessage, errorId });
+ * ```
+ */
+export declare function logAndTraceError(message: string, context?: Record<string, unknown>, originalError?: Error): TraceableError;
+/**
+ * Wrap an async function to automatically trace errors.
+ * Useful for API handlers.
+ *
+ * @example
+ * ```typescript
+ * app.post('/api/spawn', withErrorTracing(async (req, res) => {
+ *   // ... handler code
+ *   // Errors automatically get traced
+ * }, { endpoint: '/api/spawn' }));
+ * ```
+ */
+export declare function withErrorTracing<T extends (...args: unknown[]) => Promise<unknown>>(fn: T, baseContext?: Record<string, unknown>): T;
+/**
+ * Error class that includes trace information.
+ * Thrown by withErrorTracing wrapper.
+ */
+export declare class TracedError extends Error {
+    readonly errorId: string;
+    readonly userMessage: string;
+    readonly context: Record<string, unknown>;
+    constructor(traced: TraceableError);
+}
+/**
+ * Search hint for support: how to find errors in logs.
+ * Include this in documentation or support portal.
+ */
+export declare const ERROR_SEARCH_HINT = "\nTo find error details in logs, search for the error ID:\n\n  grep \"ERR-1706012345-a7f3\" /var/log/agent-relay/*.log\n\nOr in cloud logging:\n\n  fly logs -a agent-relay-cloud | grep \"ERR-1706012345-a7f3\"\n\nThe log entry will include full context: user ID, workspace ID, agent name, etc.\n";
+//# sourceMappingURL=error-tracking.d.ts.map