@agent-relay/utils 2.1.5 → 2.1.7

package/dist/cjs/discovery.js

@@ -0,0 +1,328 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var discovery_exports = {};
+__export(discovery_exports, {
+  cloudApiRequest: () => cloudApiRequest,
+  detectCloudWorkspace: () => detectCloudWorkspace,
+  discoverAgentName: () => discoverAgentName,
+  discoverSocket: () => discoverSocket,
+  getCloudEnvironmentSummary: () => getCloudEnvironmentSummary,
+  getCloudOutboxPath: () => getCloudOutboxPath,
+  getCloudSocketPath: () => getCloudSocketPath,
+  getConnectionInfo: () => getConnectionInfo,
+  getWorkspaceStatus: () => getWorkspaceStatus,
+  isCloudWorkspace: () => isCloudWorkspace
+});
+module.exports = __toCommonJS(discovery_exports);
+var import_node_fs = require("node:fs");
+var import_node_path = require("node:path");
+var import_node_os = require("node:os");
+var import_config = require("@agent-relay/config");
+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
+  };
+}
+function isCloudWorkspace() {
+  return detectCloudWorkspace() !== null;
+}
+function getCloudSocketPath(workspaceId) {
+  return `/tmp/relay/${workspaceId}/sockets/daemon.sock`;
+}
+function getCloudOutboxPath(workspaceId, agentName) {
+  return `/tmp/relay/${workspaceId}/outbox/${agentName}`;
+}
+function getDataDir() {
+  const platform = process.platform;
+  if (platform === "darwin") {
+    return (0, import_node_path.join)((0, import_node_os.homedir)(), "Library", "Application Support", "agent-relay");
+  } else if (platform === "win32") {
+    return (0, import_node_path.join)(process.env.APPDATA || (0, import_node_os.homedir)(), "agent-relay");
+  } else {
+    return (0, import_node_path.join)(
+      process.env.XDG_DATA_HOME || (0, import_node_path.join)((0, import_node_os.homedir)(), ".local", "share"),
+      "agent-relay"
+    );
+  }
+}
+function discoverSocket(options = {}) {
+  if (options.socketPath) {
+    const workspace2 = options.workspace ? {
+      workspaceId: options.workspace.workspaceId || "override",
+      cloudApiUrl: options.workspace.cloudApiUrl || ""
+    } : void 0;
+    return {
+      socketPath: options.socketPath,
+      project: workspace2?.workspaceId || "override",
+      source: "env",
+      isCloud: !!workspace2,
+      workspace: workspace2
+    };
+  }
+  const socketEnv = process.env.RELAY_SOCKET;
+  if (socketEnv) {
+    const workspace2 = detectCloudWorkspace();
+    return {
+      socketPath: socketEnv,
+      project: process.env.RELAY_PROJECT || workspace2?.workspaceId || "unknown",
+      source: "env",
+      isCloud: !!workspace2,
+      workspace: workspace2 || void 0
+    };
+  }
+  const workspace = detectCloudWorkspace();
+  if (workspace) {
+    const cloudSocket = getCloudSocketPath(workspace.workspaceId);
+    return {
+      socketPath: cloudSocket,
+      project: workspace.workspaceId,
+      source: "cloud",
+      isCloud: true,
+      workspace
+    };
+  }
+  const projectEnv = process.env.RELAY_PROJECT;
+  if (projectEnv) {
+    const dataDir2 = getDataDir();
+    const projectSocket = (0, import_node_path.join)(dataDir2, "projects", projectEnv, "daemon.sock");
+    return {
+      socketPath: projectSocket,
+      project: projectEnv,
+      source: "env",
+      isCloud: false
+    };
+  }
+  const projectRoot = (0, import_config.findProjectRoot)(process.cwd());
+  const searchDirs = [process.cwd()];
+  if (projectRoot && projectRoot !== process.cwd()) {
+    searchDirs.push(projectRoot);
+  }
+  for (const dir of searchDirs) {
+    const projectLocalSocket = (0, import_node_path.join)(dir, ".agent-relay", "relay.sock");
+    if ((0, import_node_fs.existsSync)(projectLocalSocket)) {
+      let projectId = "local";
+      const markerPath = (0, import_node_path.join)(dir, ".agent-relay", ".project");
+      if ((0, import_node_fs.existsSync)(markerPath)) {
+        try {
+          const marker = JSON.parse((0, import_node_fs.readFileSync)(markerPath, "utf-8"));
+          projectId = marker.projectId || "local";
+        } catch {
+        }
+      }
+      return {
+        socketPath: projectLocalSocket,
+        project: projectId,
+        source: "cwd",
+        isCloud: false
+      };
+    }
+  }
+  const cwdConfig = (0, import_node_path.join)(process.cwd(), ".relay", "config.json");
+  if ((0, import_node_fs.existsSync)(cwdConfig)) {
+    try {
+      const config = JSON.parse((0, import_node_fs.readFileSync)(cwdConfig, "utf-8"));
+      if (config.socketPath) {
+        return {
+          socketPath: config.socketPath,
+          project: config.project || "local",
+          source: "cwd",
+          isCloud: false
+        };
+      }
+    } catch (err) {
+      if (process.env.DEBUG || process.env.RELAY_DEBUG) {
+        console.debug("[discovery] Failed to read cwd config:", cwdConfig, err);
+      }
+    }
+  }
+  const dataDir = getDataDir();
+  const projectsDir = (0, import_node_path.join)(dataDir, "projects");
+  if ((0, import_node_fs.existsSync)(projectsDir)) {
+    try {
+      const projects = (0, import_node_fs.readdirSync)(projectsDir, { withFileTypes: true }).filter((d) => d.isDirectory()).map((d) => d.name);
+      for (const project of projects) {
+        const socketPath = (0, import_node_path.join)(projectsDir, project, "daemon.sock");
+        if ((0, import_node_fs.existsSync)(socketPath)) {
+          return {
+            socketPath,
+            project,
+            source: "scan",
+            isCloud: false
+          };
+        }
+      }
+    } catch (err) {
+      if (process.env.DEBUG || process.env.RELAY_DEBUG) {
+        console.debug("[discovery] Failed to scan projects directory:", projectsDir, err);
+      }
+    }
+  }
+  return null;
+}
+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
+  });
+}
+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;
+  }
+}
+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
+  };
+  if (discovery.workspace?.cloudApiUrl) {
+    info.daemonUrl = discovery.workspace.cloudApiUrl;
+  }
+  return info;
+}
+function getCloudEnvironmentSummary() {
+  return {
+    WORKSPACE_ID: process.env.WORKSPACE_ID,
+    CLOUD_API_URL: process.env.CLOUD_API_URL,
+    WORKSPACE_TOKEN: process.env.WORKSPACE_TOKEN ? "[set]" : void 0,
+    WORKSPACE_OWNER_USER_ID: process.env.WORKSPACE_OWNER_USER_ID,
+    RELAY_SOCKET: process.env.RELAY_SOCKET,
+    RELAY_PROJECT: process.env.RELAY_PROJECT,
+    RELAY_AGENT_NAME: process.env.RELAY_AGENT_NAME
+  };
+}
+function discoverAgentName(_discovery) {
+  const envName = process.env.RELAY_AGENT_NAME;
+  if (envName) {
+    return envName;
+  }
+  const projectRoot = (0, import_config.findProjectRoot)(process.cwd());
+  const searchDirs = [process.cwd()];
+  if (projectRoot && projectRoot !== process.cwd()) {
+    searchDirs.push(projectRoot);
+  }
+  for (const dir of searchDirs) {
+    const relayDir = (0, import_node_path.join)(dir, ".agent-relay");
+    if (!(0, import_node_fs.existsSync)(relayDir)) continue;
+    const pidIdentityPath = (0, import_node_path.join)(relayDir, `mcp-identity-${process.ppid}`);
+    if ((0, import_node_fs.existsSync)(pidIdentityPath)) {
+      try {
+        const content = (0, import_node_fs.readFileSync)(pidIdentityPath, "utf-8").trim();
+        if (content) {
+          return content;
+        }
+      } catch {
+      }
+    }
+    try {
+      const files = (0, import_node_fs.readdirSync)(relayDir, { withFileTypes: true }).filter((d) => d.isFile() && d.name.startsWith("mcp-identity-")).map((d) => ({
+        path: (0, import_node_path.join)(relayDir, d.name),
+        name: d.name
+      }));
+      if (files.length > 0) {
+        const sorted = files.map((f) => {
+          try {
+            const stat = (0, import_node_fs.statSync)(f.path);
+            return { ...f, mtime: stat.mtimeMs };
+          } catch {
+            return { ...f, mtime: 0 };
+          }
+        }).sort((a, b) => b.mtime - a.mtime);
+        const latest = sorted[0];
+        if (latest) {
+          try {
+            const content = (0, import_node_fs.readFileSync)(latest.path, "utf-8").trim();
+            if (content) {
+              return content;
+            }
+          } catch {
+          }
+        }
+      }
+    } catch {
+    }
+    const identityPath = (0, import_node_path.join)(relayDir, "mcp-identity");
+    if ((0, import_node_fs.existsSync)(identityPath)) {
+      try {
+        const content = (0, import_node_fs.readFileSync)(identityPath, "utf-8").trim();
+        if (content) {
+          return content;
+        }
+      } catch {
+      }
+    }
+  }
+  for (const dir of searchDirs) {
+    const outboxDir = (0, import_node_path.join)(dir, ".agent-relay", "outbox");
+    if ((0, import_node_fs.existsSync)(outboxDir)) {
+      try {
+        const agents = (0, import_node_fs.readdirSync)(outboxDir, { withFileTypes: true }).filter((d) => d.isDirectory()).map((d) => d.name);
+        if (agents.length === 1) {
+          return agents[0];
+        }
+      } catch {
+      }
+    }
+  }
+  return null;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  cloudApiRequest,
+  detectCloudWorkspace,
+  discoverAgentName,
+  discoverSocket,
+  getCloudEnvironmentSummary,
+  getCloudOutboxPath,
+  getCloudSocketPath,
+  getConnectionInfo,
+  getWorkspaceStatus,
+  isCloudWorkspace
+});

package/dist/cjs/errors.js

@@ -0,0 +1,81 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var errors_exports = {};
+__export(errors_exports, {
+  AgentNotFoundError: () => AgentNotFoundError,
+  ChannelNotFoundError: () => ChannelNotFoundError,
+  ConnectionError: () => ConnectionError,
+  DaemonNotRunningError: () => DaemonNotRunningError,
+  RelayError: () => RelayError,
+  SpawnError: () => SpawnError,
+  TimeoutError: () => TimeoutError
+});
+module.exports = __toCommonJS(errors_exports);
+class RelayError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "RelayError";
+  }
+}
+class DaemonNotRunningError extends RelayError {
+  constructor(message) {
+    super(message || "Relay daemon is not running. Start with: agent-relay up");
+    this.name = "DaemonNotRunningError";
+  }
+}
+class AgentNotFoundError extends RelayError {
+  constructor(agentName) {
+    super(`Agent not found: ${agentName}`);
+    this.name = "AgentNotFoundError";
+  }
+}
+class TimeoutError extends RelayError {
+  constructor(operation, timeoutMs) {
+    super(`Timeout after ${timeoutMs}ms: ${operation}`);
+    this.name = "TimeoutError";
+  }
+}
+class ConnectionError extends RelayError {
+  constructor(message) {
+    super(`Connection error: ${message}`);
+    this.name = "ConnectionError";
+  }
+}
+class ChannelNotFoundError extends RelayError {
+  constructor(channel) {
+    super(`Channel not found: ${channel}`);
+    this.name = "ChannelNotFoundError";
+  }
+}
+class SpawnError extends RelayError {
+  constructor(workerName, reason) {
+    super(`Failed to spawn worker "${workerName}": ${reason}`);
+    this.name = "SpawnError";
+  }
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  AgentNotFoundError,
+  ChannelNotFoundError,
+  ConnectionError,
+  DaemonNotRunningError,
+  RelayError,
+  SpawnError,
+  TimeoutError
+});

package/dist/discovery.d.ts

@@ -0,0 +1,123 @@
+/**
+ * Socket Discovery & Cloud Workspace Detection
+ *
+ * Single source of truth for discovering relay daemon sockets,
+ * cloud workspace environments, and agent identity.
+ *
+ * Previously duplicated in @agent-relay/mcp (cloud.ts). Now consolidated
+ * here in the SDK so both SDK and MCP use the same discovery logic.
+ */
+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>;
+}
+export interface CloudConnectionInfo {
+    socketPath: string;
+    project: string;
+    isCloud: boolean;
+    workspace?: CloudWorkspace;
+    daemonUrl?: string;
+}
+/**
+ * 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>;
+/**
+ * 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>;
+/**
+ * Discover the agent name for the MCP server.
+ *
+ * Priority order:
+ * 1. RELAY_AGENT_NAME environment variable (explicit)
+ * 2. Identity file in .agent-relay directory (written by wrapper)
+ * 3. Scan outbox directories to find agent's outbox
+ *
+ * @param _discovery - Optional discovery result (reserved for future use)
+ * @returns Agent name or null if not found
+ */
+export declare function discoverAgentName(_discovery?: DiscoveryResult | null): string | null;
+//# sourceMappingURL=discovery.d.ts.map

package/dist/discovery.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"discovery.d.ts","sourceRoot":"","sources":["../src/discovery.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAWH,MAAM,WAAW,cAAc;IAC7B,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,eAAe;IAC9B,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,KAAK,GAAG,OAAO,GAAG,KAAK,GAAG,MAAM,CAAC;IACzC,OAAO,EAAE,OAAO,CAAC;IACjB,SAAS,CAAC,EAAE,cAAc,CAAC;CAC5B;AAED,MAAM,WAAW,sBAAsB;IACrC,yCAAyC;IACzC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,mCAAmC;IACnC,SAAS,CAAC,EAAE,OAAO,CAAC,cAAc,CAAC,CAAC;CACrC;AAED,MAAM,WAAW,mBAAmB;IAClC,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,OAAO,CAAC;IACjB,SAAS,CAAC,EAAE,cAAc,CAAC;IAC3B,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAMD;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,IAAI,cAAc,GAAG,IAAI,CAc5D;AAED;;GAEG;AACH,wBAAgB,gBAAgB,IAAI,OAAO,CAE1C;AAMD;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAE9D;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,WAAW,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAEjF;AAoBD;;;;;;;;;;;;GAYG;AACH,wBAAgB,cAAc,CAAC,OAAO,GAAE,sBAA2B,GAAG,eAAe,GAAG,IAAI,CA+I3F;AAMD;;;;;;;GAOG;AACH,wBAAsB,eAAe,CACnC,SAAS,EAAE,cAAc,EACzB,IAAI,EAAE,MAAM,EACZ,OAAO,GAAE,WAAgB,GACxB,OAAO,CAAC,QAAQ,CAAC,CAgBnB;AAED;;GAEG;AACH,wBAAsB,kBAAkB,CACtC,SAAS,EAAE,cAAc,GACxB,OAAO,CAAC;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,EAAE,CAAA;CAAE,GAAG,IAAI,CAAC,CAevD;AAMD;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAC/B,OAAO,GAAE,sBAA2B,GACnC,mBAAmB,GAAG,IAAI,CAoB5B;AAED;;GAEG;AACH,wBAAgB,0BAA0B,IAAI,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAU/E;AAMD;;;;;;;;;;GAUG;AACH,wBAAgB,iBAAiB,CAAC,UAAU,CAAC,EAAE,eAAe,GAAG,IAAI,GAAG,MAAM,GAAG,IAAI,CAgHpF"}

package/dist/discovery.js

@@ -0,0 +1,439 @@
+/**
+ * Socket Discovery & Cloud Workspace Detection
+ *
+ * Single source of truth for discovering relay daemon sockets,
+ * cloud workspace environments, and agent identity.
+ *
+ * Previously duplicated in @agent-relay/mcp (cloud.ts). Now consolidated
+ * here in the SDK so both SDK and MCP use the same discovery logic.
+ */
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+import { findProjectRoot } from '@agent-relay/config';
+// ============================================================================
+// 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}`;
+}
+/**
+ * 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) {
+        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) {
+        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)
+    // Return the determined path even if the socket file doesn't exist yet
+    // (daemon may not have started)
+    const workspace = detectCloudWorkspace();
+    if (workspace) {
+        const cloudSocket = getCloudSocketPath(workspace.workspaceId);
+        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');
+        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) {
+                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('[discovery] 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('[discovery] 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;
+    }
+}
+// ============================================================================
+// Cloud Connection Factory
+// ============================================================================
+/**
+ * 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,
+        RELAY_AGENT_NAME: process.env.RELAY_AGENT_NAME,
+    };
+}
+// ============================================================================
+// Agent Identity Discovery
+// ============================================================================
+/**
+ * Discover the agent name for the MCP server.
+ *
+ * Priority order:
+ * 1. RELAY_AGENT_NAME environment variable (explicit)
+ * 2. Identity file in .agent-relay directory (written by wrapper)
+ * 3. Scan outbox directories to find agent's outbox
+ *
+ * @param _discovery - Optional discovery result (reserved for future use)
+ * @returns Agent name or null if not found
+ */
+export function discoverAgentName(_discovery) {
+    // 1. Explicit environment variable
+    const envName = process.env.RELAY_AGENT_NAME;
+    if (envName) {
+        return envName;
+    }
+    // 2. Identity file in .agent-relay directory
+    // The wrapper creates this file with the agent name
+    const projectRoot = findProjectRoot(process.cwd());
+    const searchDirs = [process.cwd()];
+    if (projectRoot && projectRoot !== process.cwd()) {
+        searchDirs.push(projectRoot);
+    }
+    for (const dir of searchDirs) {
+        const relayDir = join(dir, '.agent-relay');
+        if (!existsSync(relayDir))
+            continue;
+        // First check for per-process identity files
+        // The orchestrator writes mcp-identity-{orchestrator.pid}
+        // Try to find one by checking process.ppid and its ancestors
+        const pidIdentityPath = join(relayDir, `mcp-identity-${process.ppid}`);
+        if (existsSync(pidIdentityPath)) {
+            try {
+                const content = readFileSync(pidIdentityPath, 'utf-8').trim();
+                if (content) {
+                    return content;
+                }
+            }
+            catch {
+                // Ignore read errors
+            }
+        }
+        // Scan all mcp-identity-* files and return the most recently modified one
+        // This handles the case where MCP server's ppid doesn't match the orchestrator
+        try {
+            const files = readdirSync(relayDir, { withFileTypes: true })
+                .filter((d) => d.isFile() && d.name.startsWith('mcp-identity-'))
+                .map((d) => ({
+                path: join(relayDir, d.name),
+                name: d.name,
+            }));
+            if (files.length > 0) {
+                // Sort by mtime (most recent first) to get the latest identity
+                const sorted = files
+                    .map((f) => {
+                    try {
+                        const stat = statSync(f.path);
+                        return { ...f, mtime: stat.mtimeMs };
+                    }
+                    catch {
+                        return { ...f, mtime: 0 };
+                    }
+                })
+                    .sort((a, b) => b.mtime - a.mtime);
+                // Return the most recently modified identity file
+                const latest = sorted[0];
+                if (latest) {
+                    try {
+                        const content = readFileSync(latest.path, 'utf-8').trim();
+                        if (content) {
+                            return content;
+                        }
+                    }
+                    catch {
+                        // Ignore
+                    }
+                }
+            }
+        }
+        catch {
+            // Ignore scan errors
+        }
+        // Fallback to simple identity file (for single-agent scenarios)
+        const identityPath = join(relayDir, 'mcp-identity');
+        if (existsSync(identityPath)) {
+            try {
+                const content = readFileSync(identityPath, 'utf-8').trim();
+                if (content) {
+                    return content;
+                }
+            }
+            catch {
+                // Ignore read errors
+            }
+        }
+    }
+    // 3. Check outbox directories for a match
+    // If only one agent's outbox exists, assume we're that agent
+    for (const dir of searchDirs) {
+        const outboxDir = join(dir, '.agent-relay', 'outbox');
+        if (existsSync(outboxDir)) {
+            try {
+                const agents = readdirSync(outboxDir, { withFileTypes: true })
+                    .filter((d) => d.isDirectory())
+                    .map((d) => d.name);
+                // If there's exactly one outbox, use that agent name
+                if (agents.length === 1) {
+                    return agents[0];
+                }
+                // If there are multiple, we can't determine which one we are
+                // The wrapper should have created an identity file
+            }
+            catch {
+                // Ignore read errors
+            }
+        }
+    }
+    return null;
+}
+//# sourceMappingURL=discovery.js.map

package/dist/discovery.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"discovery.js","sourceRoot":"","sources":["../src/discovery.ts"],"names":[],"mappings":"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"}

package/dist/errors.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Error Types for Agent Relay
+ *
+ * Single source of truth for typed error classes.
+ * Previously duplicated in @agent-relay/mcp (errors.ts).
+ * Now consolidated here in the SDK for shared use.
+ */
+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/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,qBAAa,UAAW,SAAQ,KAAK;gBACvB,OAAO,EAAE,MAAM;CAI5B;AAED,qBAAa,qBAAsB,SAAQ,UAAU;gBACvC,OAAO,CAAC,EAAE,MAAM;CAI7B;AAED,qBAAa,kBAAmB,SAAQ,UAAU;gBACpC,SAAS,EAAE,MAAM;CAI9B;AAED,qBAAa,YAAa,SAAQ,UAAU;gBAC9B,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM;CAIjD;AAED,qBAAa,eAAgB,SAAQ,UAAU;gBACjC,OAAO,EAAE,MAAM;CAI5B;AAED,qBAAa,oBAAqB,SAAQ,UAAU;gBACtC,OAAO,EAAE,MAAM;CAI5B;AAED,qBAAa,UAAW,SAAQ,UAAU;gBAC5B,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM;CAI/C"}

package/dist/errors.js

@@ -0,0 +1,50 @@
+/**
+ * Error Types for Agent Relay
+ *
+ * Single source of truth for typed error classes.
+ * Previously duplicated in @agent-relay/mcp (errors.ts).
+ * Now consolidated here in the SDK for shared use.
+ */
+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/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,MAAM,OAAO,UAAW,SAAQ,KAAK;IACnC,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,YAAY,CAAC;IAC3B,CAAC;CACF;AAED,MAAM,OAAO,qBAAsB,SAAQ,UAAU;IACnD,YAAY,OAAgB;QAC1B,KAAK,CAAC,OAAO,IAAI,yDAAyD,CAAC,CAAC;QAC5E,IAAI,CAAC,IAAI,GAAG,uBAAuB,CAAC;IACtC,CAAC;CACF;AAED,MAAM,OAAO,kBAAmB,SAAQ,UAAU;IAChD,YAAY,SAAiB;QAC3B,KAAK,CAAC,oBAAoB,SAAS,EAAE,CAAC,CAAC;QACvC,IAAI,CAAC,IAAI,GAAG,oBAAoB,CAAC;IACnC,CAAC;CACF;AAED,MAAM,OAAO,YAAa,SAAQ,UAAU;IAC1C,YAAY,SAAiB,EAAE,SAAiB;QAC9C,KAAK,CAAC,iBAAiB,SAAS,OAAO,SAAS,EAAE,CAAC,CAAC;QACpD,IAAI,CAAC,IAAI,GAAG,cAAc,CAAC;IAC7B,CAAC;CACF;AAED,MAAM,OAAO,eAAgB,SAAQ,UAAU;IAC7C,YAAY,OAAe;QACzB,KAAK,CAAC,qBAAqB,OAAO,EAAE,CAAC,CAAC;QACtC,IAAI,CAAC,IAAI,GAAG,iBAAiB,CAAC;IAChC,CAAC;CACF;AAED,MAAM,OAAO,oBAAqB,SAAQ,UAAU;IAClD,YAAY,OAAe;QACzB,KAAK,CAAC,sBAAsB,OAAO,EAAE,CAAC,CAAC;QACvC,IAAI,CAAC,IAAI,GAAG,sBAAsB,CAAC;IACrC,CAAC;CACF;AAED,MAAM,OAAO,UAAW,SAAQ,UAAU;IACxC,YAAY,UAAkB,EAAE,MAAc;QAC5C,KAAK,CAAC,2BAA2B,UAAU,MAAM,MAAM,EAAE,CAAC,CAAC;QAC3D,IAAI,CAAC,IAAI,GAAG,YAAY,CAAC;IAC3B,CAAC;CACF"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-relay/utils",
-  "version": "2.1.5",
+  "version": "2.1.7",
   "description": "Shared utilities for agent-relay: logging, name generation, command resolution, update checking",
   "type": "module",
   "main": "dist/cjs/index.js",
@@ -72,6 +72,18 @@
       "import": "./dist/client-helpers.js",
       "default": "./dist/cjs/client-helpers.js"
     },
+    "./discovery": {
+      "types": "./dist/discovery.d.ts",
+      "require": "./dist/cjs/discovery.js",
+      "import": "./dist/discovery.js",
+      "default": "./dist/cjs/discovery.js"
+    },
+    "./errors": {
+      "types": "./dist/errors.d.ts",
+      "require": "./dist/cjs/errors.js",
+      "import": "./dist/errors.js",
+      "default": "./dist/cjs/errors.js"
+    },
     "./package.json": "./package.json"
   },
   "files": [
@@ -94,7 +106,8 @@
     "vitest": "^3.2.4"
   },
   "dependencies": {
-    "@agent-relay/protocol": "2.1.5",
+    "@agent-relay/config": "2.1.7",
+    "@agent-relay/protocol": "2.1.7",
     "compare-versions": "^6.1.1"
   },
   "publishConfig": {