agent-relay 1.6.0 → 2.0.4

package/packages/config/dist/relay-file-writer.d.ts

@@ -0,0 +1,200 @@
+/**
+ * Relay File Writer
+ *
+ * Provides a clean abstraction for writing relay messages and attachments
+ * to the file system with a structured directory layout.
+ *
+ * Directory structure (project-local):
+ * {projectRoot}/.agent-relay/
+ *   outbox/{agent-name}/              # Agent outbox messages
+ *   attachments/{agent-name}/{ts}/    # Attachments organized by timestamp
+ *   meta/                             # Configuration and state files
+ *
+ * For cloud workspaces with WORKSPACE_ID:
+ * /tmp/relay/{workspaceId}/
+ *   outbox/{agent-name}/
+ *   attachments/{agent-name}/{ts}/
+ *
+ * Agents should use $AGENT_RELAY_OUTBOX environment variable which is
+ * automatically set by the orchestrator to the correct path.
+ */
+export interface RelayPaths {
+    /** Root directory for relay data */
+    rootDir: string;
+    /** Outbox directory for all agents */
+    outboxDir: string;
+    /** Attachments directory for all agents */
+    attachmentsDir: string;
+    /** Meta directory for configuration/state */
+    metaDir: string;
+    /** Legacy outbox path (for backward compatibility) */
+    legacyOutboxDir: string;
+}
+export interface AgentPaths extends RelayPaths {
+    /** Agent-specific outbox directory */
+    agentOutbox: string;
+    /** Agent-specific attachments directory */
+    agentAttachments: string;
+    /** Whether this is a workspace (cloud) deployment */
+    isWorkspace: boolean;
+    /** The agent name */
+    agentName: string;
+}
+export interface WriteOptions {
+    /** Create directories if they don't exist (default: true) */
+    mkdir?: boolean;
+    /** File mode (default: 0o644) */
+    mode?: number;
+}
+export interface AttachmentResult {
+    /** Full path to the attachment */
+    path: string;
+    /** Relative path from attachments root */
+    relativePath: string;
+    /** Timestamp directory */
+    timestamp: string;
+}
+/**
+ * Utility class for writing relay messages and attachments.
+ *
+ * @example
+ * ```typescript
+ * const writer = new RelayFileWriter('MyAgent');
+ *
+ * // Write a message
+ * await writer.writeMessage('msg', `TO: Lead\n\nACK: Task received`);
+ *
+ * // Write an attachment
+ * const result = await writer.writeAttachment('screenshot.png', imageBuffer);
+ * console.log(`Attachment saved to: ${result.path}`);
+ * ```
+ */
+export declare class RelayFileWriter {
+    private readonly agentName;
+    private readonly paths;
+    private readonly workspaceId?;
+    constructor(agentName: string, workspaceId?: string);
+    /**
+     * Get the resolved paths for this agent.
+     */
+    getPaths(): AgentPaths;
+    /**
+     * Get the outbox path that agents should write to.
+     * Always returns the canonical ~/.agent-relay path.
+     * In workspace mode, this path is symlinked to the actual workspace path.
+     */
+    getOutboxPath(): string;
+    /**
+     * Get the legacy outbox path (for backwards compatibility symlinks).
+     */
+    getLegacyOutboxPath(): string;
+    /**
+     * Ensure all necessary directories exist for this agent.
+     * In workspace mode, also sets up symlinks from canonical path to workspace path.
+     */
+    ensureDirectories(): Promise<void>;
+    /**
+     * Set up symlinks for workspace mode.
+     * Creates symlink from legacy /tmp/relay-outbox path to workspace path.
+     * (The orchestrator creates the canonical→workspace symlink)
+     */
+    private setupWorkspaceSymlinks;
+    /**
+     * Helper to create a symlink, cleaning up existing path first.
+     */
+    private createSymlinkSafe;
+    /**
+     * Write a message to the agent's outbox.
+     *
+     * @param messageType - Type/name of the message (e.g., 'msg', 'ack', 'done')
+     * @param content - Message content (headers + body)
+     * @param options - Write options
+     * @returns Full path to the written file
+     *
+     * @example
+     * ```typescript
+     * await writer.writeMessage('ack', `TO: Lead\n\nACK: Task received`);
+     * ```
+     */
+    writeMessage(messageType: string, content: string, options?: WriteOptions): Promise<string>;
+    /**
+     * Write an attachment to the agent's attachments directory.
+     * Attachments are organized by timestamp to prevent collisions.
+     *
+     * @param fileName - Name of the attachment file
+     * @param data - File content (string or Buffer)
+     * @param options - Write options
+     * @returns Attachment result with paths
+     *
+     * @example
+     * ```typescript
+     * const result = await writer.writeAttachment('screenshot.png', imageBuffer);
+     * console.log(`Saved to: ${result.path}`);
+     * ```
+     */
+    writeAttachment(fileName: string, data: string | Buffer, options?: WriteOptions): Promise<AttachmentResult>;
+    /**
+     * Read a message from the agent's outbox.
+     *
+     * @param messageType - Type/name of the message
+     * @returns Message content or null if not found
+     */
+    readMessage(messageType: string): Promise<string | null>;
+    /**
+     * Delete a message from the agent's outbox.
+     *
+     * @param messageType - Type/name of the message
+     * @returns true if deleted, false if not found
+     */
+    deleteMessage(messageType: string): Promise<boolean>;
+    /**
+     * List all messages in the agent's outbox.
+     *
+     * @returns Array of message type names
+     */
+    listMessages(): Promise<string[]>;
+    /**
+     * Write metadata to the meta directory.
+     *
+     * @param key - Metadata key (file name)
+     * @param data - Metadata content (will be JSON stringified if object)
+     */
+    writeMeta(key: string, data: string | Record<string, unknown>): Promise<string>;
+    /**
+     * Read metadata from the meta directory.
+     *
+     * @param key - Metadata key (file name)
+     * @param parse - If true, parse as JSON (default: false)
+     */
+    readMeta<T = string>(key: string, parse?: false): Promise<T | null>;
+    readMeta<T>(key: string, parse: true): Promise<T | null>;
+    /**
+     * Clean up the agent's outbox (remove all messages).
+     */
+    cleanOutbox(): Promise<void>;
+}
+/**
+ * Get relay paths for an agent (without creating an instance).
+ */
+export declare function getRelayPaths(agentName: string, workspaceId?: string): AgentPaths;
+/**
+ * Get the base relay paths (not agent-specific).
+ */
+export declare function getBaseRelayPaths(workspaceId?: string): RelayPaths;
+/**
+ * Get the outbox path that should be used in agent instructions.
+ * This is the path agents will write to in their bash commands.
+ *
+ * Returns the $AGENT_RELAY_OUTBOX environment variable by default.
+ * This env var is automatically set by the orchestrator when spawning agents,
+ * and contains the correct project-local path.
+ *
+ * @param _agentNameVar - Deprecated, kept for API compatibility
+ * @returns Path template for agent instructions
+ */
+export declare function getAgentOutboxTemplate(_agentNameVar?: string): string;
+/**
+ * Ensure the base relay directories exist.
+ */
+export declare function ensureBaseDirectories(workspaceId?: string): Promise<RelayPaths>;
+//# sourceMappingURL=relay-file-writer.d.ts.map

package/packages/config/dist/relay-file-writer.js

@@ -0,0 +1,407 @@
+/**
+ * Relay File Writer
+ *
+ * Provides a clean abstraction for writing relay messages and attachments
+ * to the file system with a structured directory layout.
+ *
+ * Directory structure (project-local):
+ * {projectRoot}/.agent-relay/
+ *   outbox/{agent-name}/              # Agent outbox messages
+ *   attachments/{agent-name}/{ts}/    # Attachments organized by timestamp
+ *   meta/                             # Configuration and state files
+ *
+ * For cloud workspaces with WORKSPACE_ID:
+ * /tmp/relay/{workspaceId}/
+ *   outbox/{agent-name}/
+ *   attachments/{agent-name}/{ts}/
+ *
+ * Agents should use $AGENT_RELAY_OUTBOX environment variable which is
+ * automatically set by the orchestrator to the correct path.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import crypto from 'node:crypto';
+// ============================================================================
+// Constants
+// ============================================================================
+const MAX_SOCKET_PATH_LENGTH = 107;
+const DEFAULT_OUTBOX_DIR = 'outbox';
+const DEFAULT_ATTACHMENTS_DIR = 'attachments';
+const DEFAULT_META_DIR = 'meta';
+const LEGACY_OUTBOX_BASE = '/tmp/relay-outbox';
+// ============================================================================
+// Path Resolution
+// ============================================================================
+/**
+ * Hash a workspace ID to keep paths short (for Unix socket length limits)
+ */
+function hashWorkspaceId(workspaceId) {
+    return crypto.createHash('sha256').update(workspaceId).digest('hex').slice(0, 12);
+}
+/**
+ * Get the base directory for relay data.
+ * Priority:
+ * 1. AGENT_RELAY_DATA_DIR environment variable
+ * 2. XDG_DATA_HOME/agent-relay (Linux/macOS standard)
+ * 3. ~/.agent-relay (fallback)
+ */
+function getBaseDir() {
+    // Explicit override
+    if (process.env.AGENT_RELAY_DATA_DIR) {
+        return process.env.AGENT_RELAY_DATA_DIR;
+    }
+    // XDG Base Directory Specification
+    const xdgDataHome = process.env.XDG_DATA_HOME;
+    if (xdgDataHome) {
+        return path.join(xdgDataHome, 'agent-relay');
+    }
+    // Default: ~/.agent-relay
+    return path.join(os.homedir(), '.agent-relay');
+}
+/**
+ * Get workspace-specific paths for cloud deployments.
+ * Uses /tmp/relay/{workspaceId} to ensure workspace isolation.
+ */
+function getWorkspacePaths(workspaceId) {
+    let effectiveId = workspaceId;
+    let workspaceDir = `/tmp/relay/${workspaceId}`;
+    // Check if path would be too long for sockets
+    const testSocketPath = `${workspaceDir}/sockets/test.sock`;
+    if (testSocketPath.length > MAX_SOCKET_PATH_LENGTH) {
+        effectiveId = hashWorkspaceId(workspaceId);
+        workspaceDir = `/tmp/relay/${effectiveId}`;
+    }
+    return {
+        rootDir: workspaceDir,
+        outboxDir: path.join(workspaceDir, DEFAULT_OUTBOX_DIR),
+        attachmentsDir: path.join(workspaceDir, DEFAULT_ATTACHMENTS_DIR),
+        metaDir: path.join(workspaceDir, DEFAULT_META_DIR),
+        legacyOutboxDir: LEGACY_OUTBOX_BASE,
+    };
+}
+/**
+ * Get local (non-workspace) relay paths.
+ * Uses ~/.agent-relay for persistent storage.
+ */
+function getLocalPaths() {
+    const baseDir = getBaseDir();
+    return {
+        rootDir: baseDir,
+        outboxDir: path.join(baseDir, DEFAULT_OUTBOX_DIR),
+        attachmentsDir: path.join(baseDir, DEFAULT_ATTACHMENTS_DIR),
+        metaDir: path.join(baseDir, DEFAULT_META_DIR),
+        legacyOutboxDir: LEGACY_OUTBOX_BASE,
+    };
+}
+// ============================================================================
+// RelayFileWriter Class
+// ============================================================================
+/**
+ * Utility class for writing relay messages and attachments.
+ *
+ * @example
+ * ```typescript
+ * const writer = new RelayFileWriter('MyAgent');
+ *
+ * // Write a message
+ * await writer.writeMessage('msg', `TO: Lead\n\nACK: Task received`);
+ *
+ * // Write an attachment
+ * const result = await writer.writeAttachment('screenshot.png', imageBuffer);
+ * console.log(`Attachment saved to: ${result.path}`);
+ * ```
+ */
+export class RelayFileWriter {
+    agentName;
+    paths;
+    workspaceId;
+    constructor(agentName, workspaceId) {
+        this.agentName = agentName;
+        this.workspaceId = workspaceId ?? process.env.WORKSPACE_ID;
+        // Resolve paths based on environment
+        const basePaths = this.workspaceId
+            ? getWorkspacePaths(this.workspaceId)
+            : getLocalPaths();
+        this.paths = {
+            ...basePaths,
+            agentOutbox: path.join(basePaths.outboxDir, agentName),
+            agentAttachments: path.join(basePaths.attachmentsDir, agentName),
+            isWorkspace: !!this.workspaceId,
+            agentName,
+        };
+    }
+    /**
+     * Get the resolved paths for this agent.
+     */
+    getPaths() {
+        return { ...this.paths };
+    }
+    /**
+     * Get the outbox path that agents should write to.
+     * Always returns the canonical ~/.agent-relay path.
+     * In workspace mode, this path is symlinked to the actual workspace path.
+     */
+    getOutboxPath() {
+        // Always use the canonical path - symlinks handle workspace routing
+        return this.paths.agentOutbox;
+    }
+    /**
+     * Get the legacy outbox path (for backwards compatibility symlinks).
+     */
+    getLegacyOutboxPath() {
+        return path.join(this.paths.legacyOutboxDir, this.agentName);
+    }
+    /**
+     * Ensure all necessary directories exist for this agent.
+     * In workspace mode, also sets up symlinks from canonical path to workspace path.
+     */
+    async ensureDirectories() {
+        // Create agent-specific directories at canonical path
+        await fs.promises.mkdir(this.paths.agentOutbox, { recursive: true });
+        await fs.promises.mkdir(this.paths.agentAttachments, { recursive: true });
+        await fs.promises.mkdir(this.paths.metaDir, { recursive: true });
+        // In workspace mode, set up symlinks so canonical path routes to workspace
+        // (Note: The orchestrator handles symlink setup, this is just for standalone use)
+        if (this.paths.isWorkspace) {
+            await this.setupWorkspaceSymlinks();
+        }
+    }
+    /**
+     * Set up symlinks for workspace mode.
+     * Creates symlink from legacy /tmp/relay-outbox path to workspace path.
+     * (The orchestrator creates the canonical→workspace symlink)
+     */
+    async setupWorkspaceSymlinks() {
+        const legacyPath = path.join(this.paths.legacyOutboxDir, this.agentName);
+        try {
+            await this.createSymlinkSafe(legacyPath, this.paths.agentOutbox);
+        }
+        catch (err) {
+            console.error(`[relay-file-writer] Failed to setup workspace symlinks: ${err.message}`);
+        }
+    }
+    /**
+     * Helper to create a symlink, cleaning up existing path first.
+     */
+    async createSymlinkSafe(linkPath, targetPath) {
+        const linkParent = path.dirname(linkPath);
+        await fs.promises.mkdir(linkParent, { recursive: true });
+        try {
+            const stats = await fs.promises.lstat(linkPath);
+            if (stats.isSymbolicLink()) {
+                const target = await fs.promises.readlink(linkPath);
+                if (target === targetPath) {
+                    return; // Already correctly configured
+                }
+                await fs.promises.unlink(linkPath);
+            }
+            else if (stats.isDirectory()) {
+                await fs.promises.rm(linkPath, { recursive: true, force: true });
+            }
+        }
+        catch (err) {
+            if (err.code !== 'ENOENT') {
+                throw err;
+            }
+            // Path doesn't exist - proceed to create symlink
+        }
+        await fs.promises.symlink(targetPath, linkPath);
+    }
+    /**
+     * Write a message to the agent's outbox.
+     *
+     * @param messageType - Type/name of the message (e.g., 'msg', 'ack', 'done')
+     * @param content - Message content (headers + body)
+     * @param options - Write options
+     * @returns Full path to the written file
+     *
+     * @example
+     * ```typescript
+     * await writer.writeMessage('ack', `TO: Lead\n\nACK: Task received`);
+     * ```
+     */
+    async writeMessage(messageType, content, options = {}) {
+        const { mkdir = true, mode = 0o644 } = options;
+        if (mkdir) {
+            await this.ensureDirectories();
+        }
+        const filePath = path.join(this.paths.agentOutbox, messageType);
+        await fs.promises.writeFile(filePath, content, { mode });
+        return filePath;
+    }
+    /**
+     * Write an attachment to the agent's attachments directory.
+     * Attachments are organized by timestamp to prevent collisions.
+     *
+     * @param fileName - Name of the attachment file
+     * @param data - File content (string or Buffer)
+     * @param options - Write options
+     * @returns Attachment result with paths
+     *
+     * @example
+     * ```typescript
+     * const result = await writer.writeAttachment('screenshot.png', imageBuffer);
+     * console.log(`Saved to: ${result.path}`);
+     * ```
+     */
+    async writeAttachment(fileName, data, options = {}) {
+        const { mkdir = true, mode = 0o644 } = options;
+        // Create timestamp-based subdirectory
+        const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
+        const attachmentDir = path.join(this.paths.agentAttachments, timestamp);
+        if (mkdir) {
+            await fs.promises.mkdir(attachmentDir, { recursive: true });
+        }
+        const filePath = path.join(attachmentDir, fileName);
+        await fs.promises.writeFile(filePath, data, { mode });
+        return {
+            path: filePath,
+            relativePath: path.join(this.agentName, timestamp, fileName),
+            timestamp,
+        };
+    }
+    /**
+     * Read a message from the agent's outbox.
+     *
+     * @param messageType - Type/name of the message
+     * @returns Message content or null if not found
+     */
+    async readMessage(messageType) {
+        const filePath = path.join(this.paths.agentOutbox, messageType);
+        try {
+            return await fs.promises.readFile(filePath, 'utf-8');
+        }
+        catch (err) {
+            if (err.code === 'ENOENT') {
+                return null;
+            }
+            throw err;
+        }
+    }
+    /**
+     * Delete a message from the agent's outbox.
+     *
+     * @param messageType - Type/name of the message
+     * @returns true if deleted, false if not found
+     */
+    async deleteMessage(messageType) {
+        const filePath = path.join(this.paths.agentOutbox, messageType);
+        try {
+            await fs.promises.unlink(filePath);
+            return true;
+        }
+        catch (err) {
+            if (err.code === 'ENOENT') {
+                return false;
+            }
+            throw err;
+        }
+    }
+    /**
+     * List all messages in the agent's outbox.
+     *
+     * @returns Array of message type names
+     */
+    async listMessages() {
+        try {
+            const entries = await fs.promises.readdir(this.paths.agentOutbox);
+            return entries.filter(e => !e.startsWith('.'));
+        }
+        catch (err) {
+            if (err.code === 'ENOENT') {
+                return [];
+            }
+            throw err;
+        }
+    }
+    /**
+     * Write metadata to the meta directory.
+     *
+     * @param key - Metadata key (file name)
+     * @param data - Metadata content (will be JSON stringified if object)
+     */
+    async writeMeta(key, data) {
+        await fs.promises.mkdir(this.paths.metaDir, { recursive: true });
+        const content = typeof data === 'string' ? data : JSON.stringify(data, null, 2);
+        const filePath = path.join(this.paths.metaDir, key);
+        await fs.promises.writeFile(filePath, content);
+        return filePath;
+    }
+    async readMeta(key, parse = false) {
+        const filePath = path.join(this.paths.metaDir, key);
+        try {
+            const content = await fs.promises.readFile(filePath, 'utf-8');
+            return parse ? JSON.parse(content) : content;
+        }
+        catch (err) {
+            if (err.code === 'ENOENT') {
+                return null;
+            }
+            throw err;
+        }
+    }
+    /**
+     * Clean up the agent's outbox (remove all messages).
+     */
+    async cleanOutbox() {
+        try {
+            const entries = await fs.promises.readdir(this.paths.agentOutbox);
+            for (const entry of entries) {
+                await fs.promises.unlink(path.join(this.paths.agentOutbox, entry));
+            }
+        }
+        catch (err) {
+            if (err.code !== 'ENOENT') {
+                throw err;
+            }
+        }
+    }
+}
+// ============================================================================
+// Static Utility Functions
+// ============================================================================
+/**
+ * Get relay paths for an agent (without creating an instance).
+ */
+export function getRelayPaths(agentName, workspaceId) {
+    const writer = new RelayFileWriter(agentName, workspaceId);
+    return writer.getPaths();
+}
+/**
+ * Get the base relay paths (not agent-specific).
+ */
+export function getBaseRelayPaths(workspaceId) {
+    const effectiveWorkspaceId = workspaceId ?? process.env.WORKSPACE_ID;
+    return effectiveWorkspaceId
+        ? getWorkspacePaths(effectiveWorkspaceId)
+        : getLocalPaths();
+}
+/**
+ * Get the outbox path that should be used in agent instructions.
+ * This is the path agents will write to in their bash commands.
+ *
+ * Returns the $AGENT_RELAY_OUTBOX environment variable by default.
+ * This env var is automatically set by the orchestrator when spawning agents,
+ * and contains the correct project-local path.
+ *
+ * @param _agentNameVar - Deprecated, kept for API compatibility
+ * @returns Path template for agent instructions
+ */
+export function getAgentOutboxTemplate(_agentNameVar = '$AGENT_RELAY_NAME') {
+    // Agents should use $AGENT_RELAY_OUTBOX which is set by the orchestrator
+    // This handles both local (project-local .agent-relay/) and cloud (workspace) modes
+    return '$AGENT_RELAY_OUTBOX';
+}
+/**
+ * Ensure the base relay directories exist.
+ */
+export async function ensureBaseDirectories(workspaceId) {
+    const paths = getBaseRelayPaths(workspaceId);
+    await fs.promises.mkdir(paths.outboxDir, { recursive: true });
+    await fs.promises.mkdir(paths.attachmentsDir, { recursive: true });
+    await fs.promises.mkdir(paths.metaDir, { recursive: true });
+    await fs.promises.mkdir(paths.legacyOutboxDir, { recursive: true });
+    return paths;
+}
+//# sourceMappingURL=relay-file-writer.js.map